ruby-whatsapp 0.3.0

data/lib/ruby/whatsapp/messages/interactive/product_carousel.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Interactive
+      class ProductCarousel < Base
+        module Defaults
+          MIN_CARDS_COUNT = 2
+          MAX_CARDS_COUNT = 10
+        end
+
+        # @!attribute [rw] cards
+        #   @return [Array<Hash>]
+        attr_accessor :cards
+
+        validates :cards, presence: true, length: { minimum: Defaults::MIN_CARDS_COUNT,
+                                                    maximum: Defaults::MAX_CARDS_COUNT, }
+
+        # @param cards [Array<Hash>] The cards of the product carousel.
+        def initialize(cards:)
+          @cards = cards
+
+          validate!
+        end
+
+        class << self
+          # @return [Hash] Serialized representation of the ProductCarousel.
+          def serialize(cards:)
+            new(cards:).serialize
+          end
+        end
+
+        # @return [Hash] Serialized representation of the ProductCarousel.
+        def serialize
+          {
+            cards: serialized_cards,
+          }
+        end
+
+      private
+
+        # @return [Array<Hash>] Serialized cards.
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def serialized_cards
+          cards.map.with_index { |card, index| Card.serialize(card_index: index, **card) }
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/messages/interactive/reply_buttons/button.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Interactive
+      class ReplyButtons
+        class Button
+          include ActiveModel::Validations
+
+          module Defaults
+            TYPE = "reply"
+            MAX_ID_LENGTH = 256
+            MAX_TITLE_LENGTH = 20
+          end
+
+          # @!attribute [rw] id
+          #   @return [String]
+          attr_accessor :id
+
+          # @!attribute [rw] title
+          #   @return [String]
+          attr_accessor :title
+
+          validates :id, presence: true, length: { maximum: Defaults::MAX_ID_LENGTH }
+          validates :title, presence: true, length: { maximum: Defaults::MAX_TITLE_LENGTH }
+
+          # @param id [String] The ID of the button.
+          # @param title [String] The title of the button.
+          #  @raise [ActiveModel::ValidationError] if validation fails.
+          def initialize(id:, title:)
+            @id = id
+            @title = title
+
+            validate!
+          end
+
+          class << self
+            # @return [Hash] Serialized representation of the Button.
+            #  @raise [ActiveModel::ValidationError] if validation fails.
+            def serialize(id:, title:)
+              new(id:, title:).serialize
+            end
+          end
+
+          # @return [Hash] Serialized representation of the Button.
+          def serialize
+            {
+              type: Defaults::TYPE,
+              reply: {
+                id:,
+                title:,
+              },
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/messages/interactive/reply_buttons.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Interactive
+      class ReplyButtons < Base
+        module Defaults
+          MAX_BUTTONS = 3
+        end
+
+        # @!attribute [rw] buttons
+        #   @return [Array<Hash>]
+        attr_accessor :buttons
+
+        validates :buttons, presence: true, length: { maximum: Defaults::MAX_BUTTONS }
+
+        # @param buttons [Array<Hash>] The buttons of the reply buttons.
+        def initialize(buttons:)
+          @buttons = buttons
+
+          validate!
+        end
+
+        class << self
+          # @return [Hash] Serialized representation of the ReplyButtons.
+          def serialize(buttons:)
+            new(buttons:).serialize
+          end
+        end
+
+        # @return [Hash] Serialized representation of the ReplyButtons.
+        def serialize
+          {
+            buttons: serialized_buttons,
+          }
+        end
+
+      private
+
+        # @return [Array<Hash>] Serialized buttons.
+        def serialized_buttons
+          buttons.map { |button| Button.serialize(**button) }
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/messages/interactive/url_button.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Interactive
+      # Interactive call-to-action (CTA) URL button message. Maps a URL to a
+      # button so the raw URL does not have to appear in the message body.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-cta-url-messages
+      class UrlButton < Base
+        module Defaults
+          MAX_NAME_LENGTH = 20
+          MAX_DISPLAY_TEXT_LENGTH = 20
+        end
+
+        # @!attribute [rw] name
+        #   @return [String]
+        attr_accessor :name
+
+        # @!attribute [rw] display_text
+        #   @return [String]
+        attr_accessor :display_text
+
+        # @!attribute [rw] url
+        #   @return [String]
+        attr_accessor :url
+
+        validates :name, presence: true, length: { maximum: Defaults::MAX_NAME_LENGTH }
+        validates :display_text, presence: true, length: { maximum: Defaults::MAX_DISPLAY_TEXT_LENGTH }
+
+        # @param name [String] The name of the URL button.
+        # @param display_text [String] The text displayed on the button.
+        # @param url [String] The URL that the button links to.
+        def initialize(name:, display_text:, url:)
+          @name = name
+          @display_text = display_text
+          @url = url
+
+          validate!
+        end
+
+        class << self
+          # @return [Hash] Serialized representation of the URL button.
+          def serialize(**url_button)
+            new(**url_button).serialize
+          end
+        end
+
+        # @return [Hash] Serialized representation of the URL button.
+        def serialize
+          {
+            name:,
+            parameters:,
+          }
+        end
+
+      private
+
+        # @return [Hash] Serialized parameters for the URL button.
+        def parameters
+          {
+            display_text:,
+            url:,
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Interactive < Base
+      module Defaults
+        TYPE = "interactive"
+      end
+
+      # Maps a public action kind to its implementing class and the WhatsApp
+      # `interactive.type` value emitted in the payload. Resolution goes through
+      # this frozen whitelist — never `const_get` on caller input.
+      #
+      # NOTE: the carousel `api_type` values ("carousel"/"product_list") should be
+      # verified against the Meta docs for your API version before relying on them.
+      ACTION_TYPES = {
+        reply_buttons: { klass: ReplyButtons, api_type: "button" },
+        list_buttons: { klass: ListButtons, api_type: "list" },
+        url_button: { klass: UrlButton, api_type: "cta_url" },
+        media_carousel: { klass: MediaCarousel, api_type: "carousel" },
+        product_carousel: { klass: ProductCarousel, api_type: "product_list" },
+      }.freeze
+
+      # @!attribute [rw] type
+      #   @return [Symbol] The action kind (e.g. :reply_buttons, :list_buttons).
+      attr_accessor :type
+
+      # @!attribute [rw] header
+      #   @return [Hash, nil]
+      attr_accessor :header
+
+      # @!attribute [rw] body
+      #   @return [String]
+      attr_accessor :body
+
+      # @!attribute [rw] footer
+      #   @return [Hash, nil]
+      attr_accessor :footer
+
+      # @!attribute [rw] action
+      #   @return [Hash]
+      attr_accessor :action
+
+      validates :type, presence: true, inclusion: { in: ACTION_TYPES.keys }
+      validates :body, presence: true
+      validates :action, presence: true
+
+      # @param type [Symbol, String] The action kind (see {ACTION_TYPES}).
+      # @param body [String] The body text of the interactive message.
+      # @param action [Hash] The action content, forwarded to the action class.
+      # @param header [Hash, nil] The header content (optional).
+      # @param footer [Hash, nil] The footer content (optional).
+      # @param kwargs [Hash] Additional keyword arguments (e.g. :to).
+      #  @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(type:, body:, action:, header: nil, footer: nil, **)
+        super(**)
+
+        @type = type.to_sym
+        @body = body
+        @action = action
+        @header = header
+        @footer = footer
+
+        validate!
+      end
+
+      # @return [Hash] Serialized representation of the Interactive message.
+      def serialize
+        envelope(type: Defaults::TYPE, interactive: interactive_payload)
+      end
+
+    private
+
+      # @return [Hash] The serialized `interactive` payload.
+      def interactive_payload
+        {
+          type: action_config[:api_type],
+          header: serialized_header,
+          body: serialized_body,
+          footer: serialized_footer,
+          action: action_config[:klass].serialize(**action),
+        }.compact
+      end
+
+      # @return [Hash] The registry entry for the current action kind.
+      def action_config
+        ACTION_TYPES.fetch(type)
+      end
+
+      # @return [Hash, nil] The serialized header information.
+      def serialized_header
+        return unless header
+
+        Header.serialize(**header)
+      end
+
+      # @return [Hash, nil] The serialized footer information.
+      def serialized_footer
+        return unless footer
+
+        Footer.serialize(**footer)
+      end
+
+      # @return [Hash, nil] The serialized body information.
+      def serialized_body
+        return unless body
+
+        Body.serialize(body)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    # Location messages allow you to send a location's latitude and longitude coordinates to a WhatsApp user.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/location-messages
+    class Location < Base
+      module Defaults
+        TYPE = "location"
+      end
+
+      # @!attribute [rw] latitude
+      #   @return [Float]
+      attr_accessor :latitude
+
+      # @!attribute [rw] longitude
+      #   @return [Float]
+      attr_accessor :longitude
+
+      # @!attribute [rw] name
+      #   @return [String, nil]
+      attr_accessor :name
+
+      # @!attribute [rw] address
+      #   @return [String, nil]
+      attr_accessor :address
+
+      validates :latitude, presence: true, numericality: true
+      validates :longitude, presence: true, numericality: true
+
+      # @param latitude [Float] The latitude of the location.
+      # @param longitude [Float] The longitude of the location.
+      # @param name [String, nil] The name of the location.
+      # @param address [String, nil] The address of the location.
+      # @param kwargs [Hash] Additional keyword arguments (e.g. :to).
+      #  @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(latitude:, longitude:, name: nil, address: nil, **)
+        super(**)
+
+        @latitude = latitude
+        @longitude = longitude
+        @name = name
+        @address = address
+
+        validate!
+      end
+
+      # Serializes the location message to a hash format suitable for the WhatsApp API.
+      # @return [Hash] The serialized location message.
+      def serialize
+        envelope(type: Defaults::TYPE, location: location_payload)
+      end
+
+    private
+
+      # @return [Hash] The serialized location information.
+      def location_payload
+        {
+          latitude:,
+          longitude:,
+          name:,
+          address:,
+        }.compact
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class LocationRequest < Base
+      module Defaults
+        TYPE = "interactive"
+        INTERACTIVE_TYPE = "location_request_message"
+        ACTION_NAME = "send_location"
+      end
+
+      # @!attribute [rw] body
+      #   @return [Hash]
+      attr_accessor :body
+
+      validates :body, presence: true, length: { maximum: 1024 }
+
+      # @param body [String] The body text of the location request message.
+      # @param kwargs [Hash] Additional keyword arguments.
+      #  @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(body:, **)
+        super(**)
+
+        @body = body
+
+        validate!
+      end
+
+      def serialize
+        envelope(
+          type: Defaults::TYPE,
+          interactive: {
+            type: Defaults::INTERACTIVE_TYPE,
+            body:,
+            action: { name: Defaults::ACTION_NAME },
+          }
+        )
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    # Marks a previously received message (and every earlier message in the
+    # conversation) as read. Unlike every other message class, this has no
+    # recipient or type envelope — it targets an existing message by ID.
+    # Meta requires this within 30 days of receipt.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/mark-message-as-read
+    class MarkMessageAsRead
+      include ActiveModel::Validations
+
+      module Defaults
+        MESSAGING_PRODUCT = "whatsapp"
+        STATUS = "read"
+      end
+
+      # @!attribute [rw] message_id
+      #   @return [String]
+      attr_accessor :message_id
+
+      validates :message_id, presence: true
+
+      # @param message_id [String] The WhatsApp message ID (WAMID) to mark as read.
+      #  @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(message_id:)
+        @message_id = message_id
+
+        validate!
+      end
+
+      # @return [Hash] Serialized representation for the WhatsApp API.
+      def serialize
+        {
+          messaging_product: Defaults::MESSAGING_PRODUCT,
+          status: Defaults::STATUS,
+          message_id:,
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    # Reaction messages are emoji-reactions applied to a WhatsApp message you have received.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/reaction-messages
+    class Reaction < Base
+      module Defaults
+        TYPE = "reaction"
+      end
+
+      # @!attribute [rw] message_id
+      #   @return [String]
+      attr_accessor :message_id
+
+      # @!attribute [rw] emoji
+      #   @return [String]
+      attr_accessor :emoji
+
+      validates :message_id, presence: true
+      validate :emoji_unicode
+
+      # @param message_id [String] The ID of the message being reacted to.
+      # @param emoji [String] The emoji used for the reaction.
+      # @param kwargs [Hash] Additional keyword arguments.
+      #  @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(message_id:, emoji:, **)
+        super(**)
+
+        @message_id = message_id
+        @emoji = emoji
+
+        validate!
+      end
+
+      # Serializes the reaction message to a hash format suitable for the WhatsApp API.
+      # @return [Hash] The serialized reaction message.
+      def serialize
+        envelope(type: Defaults::TYPE, reaction: { message_id:, emoji: })
+      end
+
+    private
+
+      # Validates that the emoji is a valid Unicode emoji character.
+      # @return [void]
+      # @raise [ActiveModel::ValidationError] if the emoji is not valid.
+      def emoji_unicode
+        if @emoji.nil?
+          errors.add(:emoji, "can't be nil")
+          return
+        end
+
+        # An empty string is valid: it removes a previously sent reaction.
+        return if @emoji.empty?
+        return if @emoji.match?(/\p{Emoji}/)
+
+        errors.add(:emoji, "must be a valid emoji character")
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/messages/response/contacts.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Response
+      class Contacts
+        # @!attribute [rw] input
+        #   @return [String]
+        attr_accessor :input
+
+        # @!attribute [rw] wa_id
+        #   @return [String]
+        attr_accessor :wa_id
+
+        # @param input [String] The input value of the contact.
+        # @param wa_id [String] The WhatsApp ID of the contact.
+        def initialize(input:, wa_id:)
+          @input = input
+          @wa_id = wa_id
+        end
+
+        class << self
+          # Deserializes a hash into a Messages::Response::Contacts object.
+          # @param data [Hash] The hash representation of the contact response.
+          #   @return [Messages::Response::Contacts] The deserialized contact response object.
+          def deserialize(data)
+            new(
+              input: data["input"],
+              wa_id: data["wa_id"]
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Response
+      class Messages
+        # @!attribute [rw] id
+        #   @return [String]
+        attr_accessor :id
+
+        # @param id [String] The unique identifier of the message.
+        def initialize(id:)
+          @id = id
+        end
+
+        class << self
+          # Deserializes a hash into a Messages::Response::Messages object.
+          # @param data [Hash] The hash representation of the message response.
+          #   @return [Messages::Response::Messages] The deserialized message response object.
+          def deserialize(data)
+            new(id: data["id"])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Response
+      # @!attribute [rw] messaging_product
+      #   @return [String]
+      attr_accessor :messaging_product
+
+      # @!attribute [rw] contacts
+      #   @return [Array<Contacts>]
+      attr_accessor :contacts
+
+      # @!attribute [rw] messages
+      #   @return [Array<Messages>]
+      attr_accessor :messages
+
+      # @!attribute [rw] success
+      #   @return [Boolean, nil] Present on status-update responses (e.g. mark-message-as-read);
+      #     nil on normal message-send responses.
+      attr_accessor :success
+
+      # @param messaging_product [String] The messaging product used (e.g., "whatsapp").
+      # @param contacts [Array<Contacts>] The list of contact responses.
+      # @param messages [Array<Messages>] The list of message responses.
+      # @param success [Boolean, nil] The status-update success flag, if present.
+      def initialize(messaging_product:, contacts:, messages:, success: nil)
+        @messaging_product = messaging_product
+        @contacts = contacts
+        @messages = messages
+        @success = success
+      end
+
+      class << self
+        # Deserializes a hash into a Messages::Response object.
+        # @param data [Hash] The hash representation of the message response.
+        #   @return [Messages::Response] The deserialized message response object.
+        def deserialize(data)
+          new(
+            messaging_product: data["messaging_product"],
+            contacts: Array(data["contacts"]).map { |contact_data| Contacts.deserialize(contact_data) },
+            messages: Array(data["messages"]).map { |message_data| Messages.deserialize(message_data) },
+            success: data["success"]
+          )
+        end
+      end
+    end
+  end
+end