ruby-whatsapp 0.3.0

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    # Sticker messages display animated or static sticker images in a WhatsApp message.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/sticker-messages
+    class Sticker < Base
+      module Defaults
+        TYPE = "sticker"
+      end
+
+      # @!attribute [rw] id
+      #   @return [String]
+      attr_accessor :id
+
+      # @!attribute [rw] link
+      #   @return [String]
+      attr_accessor :link
+
+      validate :validate_id_or_link
+
+      # @param id [String, nil] ID of the uploaded media asset.
+      # @param link [String, nil] URL of a publicly hosted media asset. Prefer uploading via
+      #   Media#upload and passing +id+ for better performance.
+      # @param kwargs [Hash] Additional keyword arguments.
+      #   @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(id: nil, link: nil, **)
+        super(**)
+
+        @id = id
+        @link = link
+
+        validate!
+      end
+
+      # Serializes the sticker message to a hash format suitable for the WhatsApp API.
+      # @return [Hash] The serialized sticker message.
+      def serialize
+        envelope(type: Defaults::TYPE, sticker:)
+      end
+
+    private
+
+      # Serializes the sticker information to a hash format.
+      # @return [Hash] The serialized sticker information.
+      def sticker
+        {
+          id:,
+          link:,
+        }.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/template/component.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Template
+      # Component for template messages (header, body, button)
+      class Component
+        include ActiveModel::Validations
+
+        module Types
+          HEADER = "header"
+          BODY = "body"
+          BUTTON = "button"
+        end
+
+        module SubTypes
+          # Button sub_types
+          QUICK_REPLY = "quick_reply"
+          URL = "url"
+          COPY_CODE = "copy_code"
+        end
+
+        # @!attribute [rw] type
+        #   @return [String]
+        attr_accessor :type
+
+        # @!attribute [rw] sub_type
+        #   @return [String, nil]
+        attr_accessor :sub_type
+
+        # @!attribute [rw] parameters
+        #   @return [Array<Parameter>]
+        attr_accessor :parameters
+
+        # @!attribute [rw] index
+        #   @return [Integer, nil]
+        attr_accessor :index
+
+        validates :type, presence: true, inclusion: { in: Types.constants.map { |c| Types.const_get(c) } }
+
+        # @param type [String] The type of component (header, body, button).
+        # @param sub_type [String, nil] The sub-type for button components (quick_reply, url).
+        # @param parameters [Array<Hash, Parameter>] Array of parameter hashes.
+        # @param index [Integer, nil] Button index for multiple buttons.
+        def initialize(type:, sub_type: nil, parameters: [], index: nil)
+          @type = type
+          @sub_type = sub_type
+          @parameters = parameters.map { |param| param.is_a?(Parameter) ? param : Parameter.new(**param) }
+          @index = index
+
+          validate!
+        end
+
+        # Serializes the component to a hash format suitable for the WhatsApp API.
+        # @return [Hash] The serialized component.
+        def serialize
+          result = { type: }
+          result[:sub_type] = sub_type if sub_type
+          result[:index] = index if index
+          result[:parameters] = parameters.map(&:serialize) if parameters.any?
+
+          result.compact
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/messages/template/language.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Template
+      # Language code for template messages
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/supported-languages
+      class Language
+        include ActiveModel::Validations
+
+        # @!attribute [rw] code
+        #   @return [String]
+        attr_accessor :code
+
+        validate :validate_language_code
+
+        # @param code [String] The language code (e.g., "en_US", "pt_BR").
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(code:)
+          @code = code
+
+          validate!
+        end
+
+        # Serializes the language to a hash format suitable for the WhatsApp API.
+        # @return [Hash] The serialized language.
+        def serialize
+          {
+            code:,
+          }
+        end
+
+        class << self
+          # Serializes the language to a hash format suitable for the WhatsApp API.
+          # @param code [String] The language code.
+          # @return [Hash] The serialized language.
+          def serialize(code:)
+            new(code:).serialize
+          end
+        end
+
+      private
+
+        # Validates that the language code is supported by WhatsApp
+        # @return [void]
+        def validate_language_code
+          return if Utils::LanguageCodes.valid?(code)
+
+          errors.add(:code,
+            "is not a valid WhatsApp language code. Supported codes: #{Utils::LanguageCodes.all.join(', ')}")
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/messages/template/parameter.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Template
+      # Parameters for template components
+      class Parameter
+        include ActiveModel::Validations
+
+        module Types
+          TEXT = "text"
+          CURRENCY = "currency"
+          DATE_TIME = "date_time"
+          IMAGE = "image"
+          DOCUMENT = "document"
+          VIDEO = "video"
+          LOCATION = "location"
+          PAYLOAD = "payload"
+        end
+
+        # @!attribute [rw] type
+        #   @return [String]
+        attr_accessor :type
+
+        # @!attribute [rw] text
+        #   @return [String, nil]
+        attr_accessor :text
+
+        # @!attribute [rw] currency
+        #   @return [Hash, nil]
+        attr_accessor :currency
+
+        # @!attribute [rw] date_time
+        #   @return [Hash, nil]
+        attr_accessor :date_time
+
+        # @!attribute [rw] image
+        #   @return [Hash, nil]
+        attr_accessor :image
+
+        # @!attribute [rw] document
+        #   @return [Hash, nil]
+        attr_accessor :document
+
+        # @!attribute [rw] video
+        #   @return [Hash, nil]
+        attr_accessor :video
+
+        # @!attribute [rw] location
+        #   @return [Hash, nil]
+        attr_accessor :location
+
+        # @!attribute [rw] payload
+        #   @return [String, nil]
+        attr_accessor :payload
+
+        validates :type, presence: true, inclusion: { in: Types.constants.map { |c| Types.const_get(c) } }
+
+        # @param type [String] The parameter type (one of Types: text, currency, date_time,
+        #   image, document, video, location, payload).
+        # @param text [String, nil] The text value for text parameters.
+        # @param currency [Hash, nil] Currency details for currency parameters.
+        # @param date_time [Hash, nil] Date/time details for date_time parameters.
+        # @param image [Hash, nil] Image details for image parameters.
+        # @param document [Hash, nil] Document details for document parameters.
+        # @param video [Hash, nil] Video details for video parameters.
+        # @param location [Hash, nil] Location details for location parameters.
+        # @param payload [String, nil] Payload for button parameters.
+        def initialize(type:, text: nil, currency: nil, date_time: nil, image: nil, document: nil, video: nil,
+          location: nil, payload: nil)
+          @type = type
+          @text = text
+          @currency = currency
+          @date_time = date_time
+          @image = image
+          @document = document
+          @video = video
+          @location = location
+          @payload = payload
+
+          validate!
+        end
+
+        # Serializes the parameter to a hash format suitable for the WhatsApp API.
+        # @return [Hash] The serialized parameter.
+        def serialize
+          result = { type: }
+
+          case type
+          when Types::TEXT
+            result[:text] = text
+          when Types::CURRENCY
+            result[:currency] = currency
+          when Types::DATE_TIME
+            result[:date_time] = date_time
+          when Types::IMAGE
+            result[:image] = image
+          when Types::DOCUMENT
+            result[:document] = document
+          when Types::VIDEO
+            result[:video] = video
+          when Types::LOCATION
+            result[:location] = location
+          when Types::PAYLOAD
+            result[:payload] = payload
+          end
+
+          result.compact
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    # Template messages allow you to send marketing, utility, and authentication templates to WhatsApp users.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/template-messages
+    class Template < Base
+      module Defaults
+        TYPE = "template"
+      end
+
+      # @!attribute [rw] name
+      #   @return [String]
+      attr_accessor :name
+
+      # @!attribute [rw] language
+      #   @return [Language]
+      attr_accessor :language
+
+      # @!attribute [rw] components
+      #   @return [Array<Component>]
+      attr_accessor :components
+
+      validates :name, presence: true
+      validates :language, presence: true
+
+      # @param name [String] The template name.
+      # @param language [Hash, Language] The language configuration with code.
+      # @param components [Array<Hash, Component>] Array of component hashes (optional).
+      # @param kwargs [Hash] Additional keyword arguments.
+      #  @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(name:, language:, components: [], **)
+        super(**)
+
+        @name = name
+        @language = language.is_a?(Language) ? language : Language.new(**language)
+        @components = components.map { |comp| comp.is_a?(Component) ? comp : Component.new(**comp) }
+
+        validate!
+      end
+
+      # Serializes the template message to a hash format suitable for the WhatsApp API.
+      # @return [Hash] The serialized template message.
+      def serialize
+        envelope(type: Defaults::TYPE, template: template_payload)
+      end
+
+    private
+
+      # @return [Hash] The serialized template payload.
+      def template_payload
+        {
+          name:,
+          language: language.serialize,
+          components: components.map(&:serialize),
+        }.tap do |payload|
+          payload.delete(:components) if components.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    # Text messages are messages containing only a text body and an optional link preview.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/text-messages
+    class Text < Base
+      module Defaults
+        TYPE = "text"
+      end
+
+      # @!attribute [rw] body
+      #   @return [String]
+      attr_accessor :body
+
+      # @!attribute [rw] preview_url
+      #   @return [Boolean]
+      attr_accessor :preview_url
+
+      validates :body, presence: true, length: { maximum: 4096 }
+      validates :preview_url, inclusion: { in: [true, false] }
+
+      # @param body [String] The text of the message.
+      # @param preview_url [Boolean] Whether to enable URL preview in the message.
+      # @param kwargs [Hash] Additional keyword arguments.
+      #  @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(body:, preview_url: true, **)
+        super(**)
+
+        @body = body
+        @preview_url = preview_url
+
+        validate!
+      end
+
+      # Serializes the text message to a hash format suitable for the WhatsApp API.
+      # @return [Hash] The serialized text message.
+      def serialize
+        envelope(type: Defaults::TYPE, text: { body:, preview_url: })
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    # Video messages display a thumbnail preview of a video with an optional caption.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/video-messages
+    class Video < Base
+      module Defaults
+        TYPE = "video"
+      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.
+      # @param link [String, nil] URL of the media asset hosted on your public server.
+      # @param caption [String, nil] Video caption text (maximum 1024 characters).
+      # @param kwargs [Hash] Additional keyword arguments.
+      #  @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 video message to a hash format suitable for the WhatsApp API.
+      # @return [Hash] The serialized video message.
+      def serialize
+        envelope(type: Defaults::TYPE, video: video_payload)
+      end
+
+    private
+
+      # @return [Hash] The serialized video payload.
+      def video_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.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    include ResponseHandling
+    extend ResponseHandling
+
+    # Maps a public message kind to its implementing class. Resolution goes
+    # through this frozen whitelist (never `const_get` on caller input), so an
+    # unknown or hostile `kind` can only raise, never resolve an arbitrary
+    # constant.
+    KINDS = {
+      text: Text,
+      image: Image,
+      audio: Audio,
+      video: Video,
+      document: Document,
+      sticker: Sticker,
+      contacts: Contacts,
+      reaction: Reaction,
+      location: Location,
+      address: Address,
+      location_request: LocationRequest,
+      template: Template,
+      interactive: Interactive,
+    }.freeze
+
+    class << self
+      # Defines a `send_<kind>!` convenience class method for every kind in
+      # KINDS (e.g. `send_text!`, `send_template!`), equivalent to
+      # `new(kind:, payload:, client:).send!`. Adding a kind to KINDS above
+      # automatically gets one of these for free.
+      KINDS.each_key do |kind|
+        define_method(:"send_#{kind}!") do |client: Client.new, **payload|
+          new(kind:, payload:, client:).send!
+        end
+      end
+
+      # Marks a previously received message as read. Deliberately not part of
+      # KINDS: this action has no recipient/type envelope, so it can't be
+      # dispatched through the kind:/payload: factory the way the rest of the
+      # message kinds are.
+      # @param message_id [String] The WhatsApp message ID (WAMID) to mark as read.
+      # @param client [Whatsapp::Client] The WhatsApp client instance
+      # @return [Whatsapp::Messages::Response]
+      # @raise [ActiveModel::ValidationError] if message_id is missing
+      # @raise [Whatsapp::RequestError] if the request fails
+      def mark_message_as_read!(message_id:, client: Client.new)
+        payload = MarkMessageAsRead.new(message_id:)
+
+        response = client.connection.post(
+          client.path_for(client.phone_id, "messages"),
+          json: payload.serialize
+        )
+
+        checked_response = handle_response!(response, error_class: RequestError, action: "mark message as read")
+        Response.deserialize(parse_json(checked_response))
+      end
+    end
+
+    class PayloadError < Whatsapp::Error; end
+
+    # @!attribute [rw] payload
+    #   @return [Whatsapp::Messages::Base]
+    attr_accessor :payload
+
+    # @!attribute [rw] client
+    #   @return [Whatsapp::Client]
+    attr_accessor :client
+
+    # @param kind [Symbol, String] The type of message (e.g., :text, :template)
+    # @param payload [Hash] The message payload passed to the message class
+    # @param client [Whatsapp::Client] The WhatsApp client instance
+    # @raise [PayloadError] if the kind is unknown
+    def initialize(kind:, payload:, client: Client.new)
+      klass = KINDS.fetch(kind.to_sym) do
+        raise PayloadError, "Unknown message kind: #{kind.inspect}. Known kinds: #{KINDS.keys.join(', ')}"
+      end
+
+      @payload = klass.new(**payload)
+      @client = client
+    end
+
+    # Sends the message to the WhatsApp API.
+    #   @return [Whatsapp::Messages::Response] The response from the API
+    #   @raise [Whatsapp::Messages::PayloadError] if the payload is invalid
+    #   @raise [Whatsapp::RequestError] if the request fails
+    def send!
+      raise PayloadError, "Invalid message: #{payload.errors.full_messages.join(', ')}" unless payload.valid?
+
+      response = perform_request!
+      parse!(response)
+    end
+
+  private
+
+    # Performs the HTTP request to send the message.
+    #   @return [HTTP::Response] The successful HTTP response from the API
+    #   @raise [Whatsapp::RequestError] if the request fails
+    def perform_request!
+      response = client.connection.post(
+        client.path_for(client.phone_id, "messages"),
+        json: payload.serialize
+      )
+
+      handle_response!(response, error_class: RequestError, action: "send message")
+    end
+
+    # Parses the HTTP response into a Whatsapp::Messages::Response object.
+    #   @param response [HTTP::Response] The HTTP response from the API
+    #   @return [Whatsapp::Messages::Response] The parsed response object
+    def parse!(response)
+      Response.deserialize(parse_json(response))
+    end
+  end
+end

data/lib/ruby/whatsapp/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  # Registers `rake whatsapp:install:webhook` with the host Rails app. Only
+  # defined when Rails is already loaded — this gem has no Rails dependency of
+  # its own. Deliberately excluded from Zeitwerk (see `lib/ruby/whatsapp.rb`)
+  # and required eagerly instead: Rails discovers Railtie subclasses at boot by
+  # class definition, so autoloading it lazily would be too late.
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("../../tasks/whatsapp.rake", __dir__)
+    end
+  end
+end

data/lib/ruby/whatsapp/request_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class RequestError < Whatsapp::Error; end
+end

data/lib/ruby/whatsapp/response_handling.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  # Shared handling of HTTP responses for API operations.
+  module ResponseHandling
+    # Maximum number of response-body characters to include in error messages,
+    # to avoid leaking large or sensitive payloads into logs.
+    MAX_ERROR_BODY = 500
+
+  private
+
+    # Returns the response when successful, otherwise raises error_class with a
+    # message describing the failed action and a truncated body.
+    # @param response [HTTP::Response]
+    # @param error_class [Class] the exception class to raise on failure
+    # @param action [String] a short description of the attempted action
+    # @return [HTTP::Response] the successful response
+    def handle_response!(response, error_class:, action:)
+      return response if response.status.success?
+
+      raise error_class, "Failed to #{action}: #{response.status} - #{truncate_body(response)}"
+    end
+
+    # Parses a response body as JSON, naming the format instead of inferring it.
+    #
+    # The Graph API labels its JSON responses `text/javascript`, which the http gem
+    # has no MIME handler for — `HTTP::Response#parse` with no argument raises
+    # `HTTP::Error: Unknown MIME type: text/javascript`. Every endpoint this gem
+    # talks to returns JSON, so the format is always safe to state outright.
+    # @param response [HTTP::Response]
+    # @return [Hash, Array] the parsed body
+    def parse_json(response)
+      response.parse(:json)
+    end
+
+    # @return [String] the response body truncated to MAX_ERROR_BODY characters
+    def truncate_body(response)
+      body = response.body.to_s
+      return body if body.length <= MAX_ERROR_BODY
+
+      "#{body[0, MAX_ERROR_BODY]}… (truncated)"
+    end
+  end
+end