ruby-whatsapp 0.3.0

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Base
+      include ActiveModel::Validations
+
+      module Messaging
+        PRODUCT = "whatsapp"
+        RECIPIENT_TYPE = "individual"
+      end
+
+      # @!attribute [rw] to
+      #   @return [String]
+      attr_accessor :to
+
+      validates :to, presence: true
+
+      # @param to [String] The recipient's phone number.
+      #  @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(to:)
+        @to = to
+      end
+
+      def serialize
+        raise NotImplementedError, "Subclasses must implement the serialize method"
+      end
+
+    protected
+
+      # Builds the common message envelope shared by all message types.
+      # @param type [String] the WhatsApp message type (e.g. "text")
+      # @param body [Hash] the type-specific payload merged into the envelope
+      # @return [Hash]
+      def envelope(type:, **body)
+        {
+          messaging_product: Messaging::PRODUCT,
+          recipient_type: Messaging::RECIPIENT_TYPE,
+          to:,
+          type:,
+          **body,
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Contacts
+      # Represents a physical address entry in a contact message.
+      # All fields are optional.
+      class Address
+        include ActiveModel::Validations
+
+        module Types
+          HOME = "HOME"
+          WORK = "WORK"
+          OTHER = "OTHER"
+
+          ALL = [HOME, WORK, OTHER].freeze
+        end
+
+        # @!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
+
+        validates :type, inclusion: { in: Types::ALL }, allow_nil: true
+
+        # @param street [String, nil]
+        # @param city [String, nil]
+        # @param state [String, nil]
+        # @param zip [String, nil]
+        # @param country [String, nil]
+        # @param country_code [String, nil] ISO 3166-1 alpha-2 code (e.g. "US").
+        # @param type [String, nil] Address type. One of HOME, WORK, OTHER.
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        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
+
+          validate!
+        end
+
+        # @return [Hash] The serialized address payload.
+        def serialize
+          {
+            street:,
+            city:,
+            state:,
+            zip:,
+            country:,
+            country_code:,
+            type:,
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Contacts
+      # Represents a single contact entry within a contacts message.
+      class Contact
+        include ActiveModel::Validations
+
+        # @!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
+
+        validates :name, presence: true
+
+        # @param name [Hash, Name] The contact's name. formatted_name is required.
+        # @param phones [Array<Hash, Phone>] Phone numbers.
+        # @param emails [Array<Hash, Email>] Email addresses.
+        # @param addresses [Array<Hash, Address>] Physical addresses.
+        # @param org [Hash, Org, nil] Organization details.
+        # @param urls [Array<Hash, Url>] URLs.
+        # @param birthday [String, nil] Birthday in YYYY-MM-DD format.
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(name:, phones: [], emails: [], addresses: [], org: nil, urls: [], birthday: nil)
+          @name = name.is_a?(Name) ? name : Name.new(**name)
+          @phones = phones.map { |p| p.is_a?(Phone) ? p : Phone.new(**p) }
+          @emails = emails.map { |e| e.is_a?(Email) ? e : Email.new(**e) }
+          @addresses = addresses.map { |a| a.is_a?(Address) ? a : Address.new(**a) }
+          @org = if org
+                   org.is_a?(Org) ? org : Org.new(**org)
+                 end
+          @urls = urls.map { |u| u.is_a?(Url) ? u : Url.new(**u) }
+          @birthday = birthday
+
+          validate!
+        end
+
+        # @return [Hash] The serialized contact payload.
+        def serialize
+          payload = { name: name.serialize }
+
+          payload[:phones] = phones.map(&:serialize) if phones.any?
+          payload[:emails] = emails.map(&:serialize) if emails.any?
+          payload[:addresses] = addresses.map(&:serialize) if addresses.any?
+          payload[:org] = org.serialize if org
+          payload[:urls] = urls.map(&:serialize) if urls.any?
+          payload[:birthday] = birthday if birthday
+
+          payload
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Contacts
+      # Represents an email entry in a contact message.
+      class Email
+        include ActiveModel::Validations
+
+        module Types
+          HOME = "HOME"
+          WORK = "WORK"
+          OTHER = "OTHER"
+
+          ALL = [HOME, WORK, OTHER].freeze
+        end
+
+        # @!attribute [rw] email
+        #   @return [String]
+        attr_accessor :email
+
+        # @!attribute [rw] type
+        #   @return [String, nil]
+        attr_accessor :type
+
+        validates :email, presence: true
+        validates :type, inclusion: { in: Types::ALL }, allow_nil: true
+
+        # @param email [String] The email address.
+        # @param type [String, nil] Email type. One of HOME, WORK, OTHER.
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(email:, type: nil)
+          @email = email
+          @type = type
+
+          validate!
+        end
+
+        # @return [Hash] The serialized email payload.
+        def serialize
+          {
+            email:,
+            type:,
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Contacts
+      # Represents the name component of a contact message.
+      class Name
+        include ActiveModel::Validations
+
+        # @!attribute [rw] formatted_name
+        #   @return [String] The contact's full display name. Required.
+        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
+
+        validates :formatted_name, presence: true
+
+        # @param formatted_name [String] The contact's full display name.
+        # @param first_name [String, nil]
+        # @param last_name [String, nil]
+        # @param middle_name [String, nil]
+        # @param prefix [String, nil]
+        # @param suffix [String, nil]
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        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
+
+          validate!
+        end
+
+        # @return [Hash] The serialized name payload.
+        def serialize
+          {
+            formatted_name:,
+            first_name:,
+            last_name:,
+            middle_name:,
+            prefix:,
+            suffix:,
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Contacts
+      # Represents the organization details of a contact message.
+      # All fields are optional.
+      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
+
+        # @param company [String, nil]
+        # @param department [String, nil]
+        # @param title [String, nil]
+        def initialize(company: nil, department: nil, title: nil)
+          @company = company
+          @department = department
+          @title = title
+        end
+
+        # @return [Hash] The serialized org payload.
+        def serialize
+          {
+            company:,
+            department:,
+            title:,
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Contacts
+      # Represents a phone number entry in a contact message.
+      class Phone
+        include ActiveModel::Validations
+
+        module Types
+          CELL = "CELL"
+          MAIN = "MAIN"
+          IPHONE = "IPHONE"
+          HOME = "HOME"
+          WORK = "WORK"
+          OTHER = "OTHER"
+
+          ALL = [CELL, MAIN, IPHONE, HOME, WORK, OTHER].freeze
+        end
+
+        # @!attribute [rw] phone
+        #   @return [String]
+        attr_accessor :phone
+
+        # @!attribute [rw] type
+        #   @return [String, nil]
+        attr_accessor :type
+
+        # @!attribute [rw] wa_id
+        #   @return [String, nil]
+        attr_accessor :wa_id
+
+        validates :phone, presence: true
+        validates :type, inclusion: { in: Types::ALL }, allow_nil: true
+
+        # @param phone [String] The phone number, including country code.
+        # @param type [String, nil] Phone type. One of CELL, MAIN, IPHONE, HOME, WORK, OTHER.
+        # @param wa_id [String, nil] The WhatsApp ID for this phone number.
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(phone:, type: nil, wa_id: nil)
+          @phone = phone
+          @type = type
+          @wa_id = wa_id
+
+          validate!
+        end
+
+        # @return [Hash] The serialized phone payload.
+        def serialize
+          {
+            phone:,
+            type:,
+            wa_id:,
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Contacts
+      # Represents a URL entry in a contact message.
+      class Url
+        include ActiveModel::Validations
+
+        module Types
+          WEBSITE = "WEBSITE"
+          HOMEPAGE = "HOMEPAGE"
+          WORK = "WORK"
+          HOME = "HOME"
+          OTHER = "OTHER"
+
+          ALL = [WEBSITE, HOMEPAGE, WORK, HOME, OTHER].freeze
+        end
+
+        # @!attribute [rw] url
+        #   @return [String]
+        attr_accessor :url
+
+        # @!attribute [rw] type
+        #   @return [String, nil]
+        attr_accessor :type
+
+        validates :url, presence: true
+        validates :type, inclusion: { in: Types::ALL }, allow_nil: true
+
+        # @param url [String] The URL.
+        # @param type [String, nil] URL type. One of WEBSITE, HOMEPAGE, WORK, HOME, OTHER.
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(url:, type: nil)
+          @url = url
+          @type = type
+
+          validate!
+        end
+
+        # @return [Hash] The serialized url payload.
+        def serialize
+          {
+            url:,
+            type:,
+          }.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    # Contacts messages allow you to send rich contact information directly to WhatsApp users,
+    # such as names, phone numbers, physical addresses, and email addresses.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/contacts-messages
+    class Contacts < Base
+      module Defaults
+        TYPE = "contacts"
+      end
+
+      # @!attribute [rw] contacts
+      #   @return [Array<Contact>]
+      attr_accessor :contacts
+
+      validates :contacts, presence: true, length: { maximum: 1 }
+
+      # @param contacts [Array<Hash, Contact>] Array with exactly one contact.
+      # @param kwargs [Hash] Additional keyword arguments passed to Base (:to).
+      #  @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(contacts:, **)
+        super(**)
+
+        @contacts = contacts.map { |c| c.is_a?(Contact) ? c : Contact.new(**c) }
+
+        validate!
+      end
+
+      # Serializes the contacts message to a hash format suitable for the WhatsApp API.
+      # @return [Hash] The serialized contacts message.
+      def serialize
+        envelope(type: Defaults::TYPE, contacts: contacts.map(&:serialize))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    # Document messages allow you to send a document file with an optional caption and custom filename.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/document-messages
+    #
+    # To send a document you must either:
+    #   - Upload the document via Whatsapp::Media#upload to obtain a media_id, then pass it as `id`
+    #   - Pass a publicly hosted URL as `link` (not recommended by Meta)
+    class Document < Base
+      module Defaults
+        TYPE = "document"
+      end
+
+      # @!attribute [rw] id
+      #   @return [String, nil]
+      attr_accessor :id
+
+      # @!attribute [rw] link
+      #   @return [String, nil]
+      attr_accessor :link
+
+      # @!attribute [rw] caption
+      #   @return [String, nil]
+      attr_accessor :caption
+
+      # @!attribute [rw] filename
+      #   @return [String, nil]
+      attr_accessor :filename
+
+      validate :validate_id_or_link
+      validates :caption, length: { maximum: 1024 }, allow_nil: true
+
+      # @param id [String, nil] ID of the uploaded media asset (from Media#upload).
+      # @param link [String, nil] URL of the document hosted on a public server.
+      # @param caption [String, nil] Document caption text (maximum 1024 characters).
+      # @param filename [String, nil] Custom filename displayed in the chat (e.g. "invoice.pdf").
+      # @param kwargs [Hash] Additional keyword arguments passed to Base (:to).
+      #  @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(id: nil, link: nil, caption: nil, filename: nil, **)
+        super(**)
+
+        @id = id
+        @link = link
+        @caption = caption
+        @filename = filename
+
+        validate!
+      end
+
+      # Serializes the document message to a hash format suitable for the WhatsApp API.
+      # @return [Hash] The serialized document message.
+      def serialize
+        envelope(type: Defaults::TYPE, document: document_payload)
+      end
+
+    private
+
+      # @return [Hash] The serialized document payload.
+      def document_payload
+        {
+          id:,
+          link:,
+          caption:,
+          filename:,
+        }.compact
+      end
+
+      # Validates that either id or link is present.
+      # @return [void]
+      def validate_id_or_link
+        return if id.present? || link.present?
+
+        errors.add(:base, "Either id or link must be present")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    # Image messages display an image with an optional caption.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/image-messages
+    #
+    # To send an image you must either:
+    #   - Upload the image via Whatsapp::Media#upload to obtain a media_id, then pass it as `id`
+    #   - Pass a publicly hosted URL as `link` (not recommended by Meta)
+    class Image < Base
+      module Defaults
+        TYPE = "image"
+      end
+
+      # @!attribute [rw] id
+      #   @return [String, nil]
+      attr_accessor :id
+
+      # @!attribute [rw] link
+      #   @return [String, nil]
+      attr_accessor :link
+
+      # @!attribute [rw] caption
+      #   @return [String, nil]
+      attr_accessor :caption
+
+      validate :validate_id_or_link
+      validates :caption, length: { maximum: 1024 }, allow_nil: true
+
+      # @param id [String, nil] ID of the uploaded media asset (from Media#upload).
+      # @param link [String, nil] URL of the image hosted on a public server.
+      # @param caption [String, nil] Image caption text (maximum 1024 characters).
+      # @param kwargs [Hash] Additional keyword arguments passed to Base (:to).
+      #  @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(id: nil, link: nil, caption: nil, **)
+        super(**)
+
+        @id = id
+        @link = link
+        @caption = caption
+
+        validate!
+      end
+
+      # Serializes the image message to a hash format suitable for the WhatsApp API.
+      # @return [Hash] The serialized image message.
+      def serialize
+        envelope(type: Defaults::TYPE, image: image_payload)
+      end
+
+    private
+
+      # @return [Hash] The serialized image payload.
+      def image_payload
+        {
+          id:,
+          link:,
+          caption:,
+        }.compact
+      end
+
+      # Validates that either id or link is present.
+      # @return [void]
+      def validate_id_or_link
+        return if id.present? || link.present?
+
+        errors.add(:base, "Either id or link must be present")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Interactive
+      class Base
+        include ActiveModel::Validations
+
+        def serialize
+          raise NotImplementedError, "Subclasses must implement the serialize method"
+        end
+      end
+    end
+  end
+end