ruby-whatsapp 0.3.0

data/lib/ruby/whatsapp/client.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Client
+    # Default request timeout in seconds.
+    DEFAULT_TIMEOUT = 30
+
+    # @!attribute [rw] host
+    # @return [String]
+    attr_accessor :host
+
+    # @!attribute [rw] version
+    # @return [String]
+    attr_accessor :version
+
+    # @!attribute [rw] api_key
+    # @return [String]
+    attr_accessor :api_key
+
+    # @!attribute [rw] phone_id
+    # @return [String]
+    attr_accessor :phone_id
+
+    # @!attribute [rw] waba_id
+    #   The WhatsApp Business Account ID. Used by account-scoped endpoints such as
+    #   template management, which address the WABA rather than a phone number.
+    #   @return [String, nil]
+    attr_accessor :waba_id
+
+    # @param host [String] The API origin (e.g. "https://graph.facebook.com")
+    # @param version [String] The API version (e.g. "v24.0")
+    # @param api_key [String] The API key for authentication
+    # @param phone_id [String] The WhatsApp phone number ID
+    # @param waba_id [String] The WhatsApp Business Account ID
+    # @param timeout [Integer] The request timeout in seconds
+    # @param logger [Logger, nil] The logger instance for instrumentation (optional)
+    def initialize(
+      host: Whatsapp.configuration.host,
+      version: Whatsapp.configuration.version,
+      api_key: Whatsapp.configuration.api_key,
+      phone_id: Whatsapp.configuration.phone_id,
+      waba_id: Whatsapp.configuration.waba_id,
+      timeout: DEFAULT_TIMEOUT,
+      logger: nil
+    )
+      @host = host
+      @version = version
+      @api_key = api_key
+      @phone_id = phone_id
+      @waba_id = waba_id
+      @timeout = timeout
+      @logger = logger
+    end
+
+    # Sets up and returns the persistent HTTP client, authenticated and instrumented.
+    #
+    # The persistent base is the origin only — `HTTP.persistent` normalizes its
+    # argument to the origin, so the API version must NOT be baked into it or it
+    # is silently dropped. The version is carried per-request via {#path_for}.
+    # @return [HTTP::Client] The configured HTTP client
+    def connection
+      @connection ||= begin
+        http = HTTP.persistent(@host)
+        http = http.auth("Bearer #{@api_key}") if @api_key
+        http = http.use(instrumentation: { instrumenter: Instrumentation.new(@logger) }) if @logger
+        http = http.timeout(@timeout) if @timeout
+
+        http
+      end
+    end
+
+    # Builds a versioned request path.
+    # @example
+    #   path_for(phone_id, "messages") #=> "/v24.0/<phone_id>/messages"
+    #   path_for(media_id)             #=> "/v24.0/<media_id>"
+    # @param segments [Array<String>] Path segments appended after the version.
+    # @return [String] The full request path.
+    def path_for(*segments)
+      "/#{[version, *segments].join('/')}"
+    end
+  end
+end

data/lib/ruby/whatsapp/configuration.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Configuration
+    module Defaults
+      HOST = "https://graph.facebook.com"
+      VERSION = "v24.0"
+      # Hosts allowed to receive the API bearer token during media downloads.
+      # Meta serves media from these hosts; anything else is refused so the token
+      # is never sent to an attacker-influenced URL.
+      MEDIA_HOST_ALLOWLIST = %w[lookaside.fbsbx.com mmg.whatsapp.net graph.facebook.com].freeze
+    end
+
+    # @!attribute [rw] host
+    # @return [String]
+    attr_accessor :host
+
+    # @!attribute [rw] version
+    # @return [String]
+    attr_accessor :version
+
+    # @!attribute [rw] api_key
+    # @return [String]
+    attr_accessor :api_key
+
+    # @!attribute [rw] phone_id
+    # @return [String]
+    attr_accessor :phone_id
+
+    # @!attribute [rw] waba_id
+    # @return [String]
+    attr_accessor :waba_id
+
+    # @!attribute [rw] media_host_allowlist
+    # @return [Array<String>]
+    attr_accessor :media_host_allowlist
+
+    # @!attribute [rw] verify_token
+    #   The token Meta must echo back during the webhook GET verification handshake.
+    #   @return [String, nil]
+    attr_accessor :verify_token
+
+    # @!attribute [rw] app_secret
+    #   Used to verify the `X-Hub-Signature-256` header on incoming webhook POSTs.
+    #   @return [String, nil]
+    attr_accessor :app_secret
+
+    # @param host [String] The API origin
+    # @param version [String] The API version
+    # @param api_key [String] The API key for authentication
+    # @param phone_id [String] The phone ID associated with the WhatsApp Business Account
+    # @param waba_id [String] The WhatsApp Business Account ID
+    # @param media_host_allowlist [Array<String>] Hosts allowed for media downloads
+    # @param verify_token [String, nil] The default webhook verification token
+    # @param app_secret [String, nil] The default webhook signing secret
+    def initialize(host: Defaults::HOST, version: Defaults::VERSION, api_key: nil, phone_id: nil,
+      waba_id: nil, media_host_allowlist: Defaults::MEDIA_HOST_ALLOWLIST, verify_token: nil, app_secret: nil)
+      @host = host
+      @version = version
+      @api_key = api_key
+      @phone_id = phone_id
+      @waba_id = waba_id
+      @media_host_allowlist = media_host_allowlist
+      @verify_token = verify_token
+      @app_secret = app_secret
+    end
+
+    # Redacts the api_key, app_secret, and verify_token so they never leak into logs or console output.
+    # @return [String]
+    def inspect
+      redacted_api_key = api_key.nil? ? "nil" : "[REDACTED]"
+      redacted_app_secret = app_secret.nil? ? "nil" : "[REDACTED]"
+      redacted_verify_token = verify_token.nil? ? "nil" : "[REDACTED]"
+      "#<#{self.class.name} host=#{host.inspect} version=#{version.inspect} " \
+        "api_key=#{redacted_api_key} phone_id=#{phone_id.inspect} waba_id=#{waba_id.inspect} " \
+        "verify_token=#{redacted_verify_token} app_secret=#{redacted_app_secret}>"
+    end
+  end
+end

data/lib/ruby/whatsapp/instrumentation.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  # Instrumentation for logging HTTP requests and responses.
+  class Instrumentation
+    # @param logger [Logger] The logger instance to use for logging.
+    def initialize(logger)
+      @logger = logger
+    end
+
+    # @param name [String] The name of the event.
+    # @param payload [Hash] - optional - The payload containing event data.
+    def instrument(name, payload = {})
+      error = payload[:error]
+      return unless error
+
+      @logger.error("#{name}: #{error.message}")
+    end
+
+    # @param payload [Hash] The payload containing event data.
+    def start(_, payload)
+      request = payload[:request]
+      uri = request.uri
+      # Log without the query string so identifiers/secrets in params are not logged.
+      @logger.info("#{request.verb.to_s.upcase} #{uri.scheme}://#{uri.host}#{uri.path}")
+    end
+
+    # @param payload [Hash] The payload containing event data.
+    def finish(_, payload)
+      response = payload[:response]
+      @logger.info("#{response.status.code} #{response.status.reason}")
+    end
+  end
+end

data/lib/ruby/whatsapp/media.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  # Media class for uploading, retrieving, downloading, and deleting media assets.
+  # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/media
+  class Media
+    include ResponseHandling
+
+    class MediaError < Whatsapp::Error; end
+
+    # @!attribute [rw] client
+    #   @return [Whatsapp::Client]
+    attr_accessor :client
+
+    # @param client [Whatsapp::Client] The WhatsApp client instance
+    # @param media_host_allowlist [Array<String>] Hosts allowed to receive the
+    #   bearer token during downloads (defaults to the global configuration).
+    def initialize(client: Client.new, media_host_allowlist: Whatsapp.configuration.media_host_allowlist)
+      @client = client
+      @media_host_allowlist = media_host_allowlist
+    end
+
+    # Uploads a media file to WhatsApp.
+    # @param file_path [String] Path to the file to upload
+    # @param type [String] MIME type of the file (e.g., "image/jpeg", "video/mp4")
+    # @return [String] The media ID
+    # @raise [MediaError] if the file is missing or the upload fails
+    def upload(file_path:, type:)
+      raise MediaError, "File not found: #{file_path}" unless File.exist?(file_path)
+
+      response = client.connection.post(
+        client.path_for(client.phone_id, "media"),
+        form: {
+          messaging_product: "whatsapp",
+          file: HTTP::FormData::File.new(file_path, content_type: type),
+        }
+      )
+
+      parse_json(handle_response!(response, error_class: MediaError, action: "upload media"))["id"]
+    end
+
+    # Retrieves the URL for a media asset.
+    # @param media_id [String] The media ID
+    # @return [Hash] Hash containing url, mime_type, sha256, file_size, and id
+    # @raise [MediaError] if the retrieval fails
+    def get_url(media_id:)
+      response = client.connection.get(
+        client.path_for(media_id),
+        params: { phone_number_id: client.phone_id }
+      )
+
+      parse_json(handle_response!(response, error_class: MediaError, action: "get media URL"))
+    end
+
+    # Downloads media from a media URL.
+    #
+    # The bearer token is attached to the request, so the URL is validated first:
+    # it must be HTTPS and its host must be on the allowlist. This prevents the
+    # token being sent to an attacker-influenced URL (media URLs commonly arrive
+    # from inbound webhooks).
+    # @param url [String] The media URL (valid for 5 minutes)
+    # @param save_to [String] Path where to save the downloaded file
+    # @return [String] Path to the saved file
+    # @raise [MediaError] if the URL is untrusted or the download fails
+    def download(url:, save_to:)
+      uri = parse_download_url(url)
+
+      response = HTTP.timeout(Client::DEFAULT_TIMEOUT)
+        .auth("Bearer #{client.api_key}")
+        .get(uri.to_s)
+
+      handle_response!(response, error_class: MediaError, action: "download media")
+      stream_to_file(response, save_to)
+
+      save_to
+    end
+
+    # Deletes a media asset.
+    # @param media_id [String] The media ID
+    # @return [Boolean] true if successful
+    # @raise [MediaError] if the deletion fails
+    def delete(media_id:)
+      response = client.connection.delete(
+        client.path_for(media_id),
+        params: { phone_number_id: client.phone_id }
+      )
+
+      parsed = parse_json(handle_response!(response, error_class: MediaError, action: "delete media"))
+      parsed.is_a?(Hash) && parsed["success"] == true
+    end
+
+  private
+
+    # Parses and validates a download URL (HTTPS + allowlisted host).
+    # @return [URI::HTTPS]
+    # @raise [MediaError] if the URL is invalid, not HTTPS, or not allowlisted
+    def parse_download_url(url)
+      uri =
+        begin
+          URI.parse(url)
+        rescue URI::InvalidURIError => e
+          raise MediaError, "Invalid media URL: #{e.message}"
+        end
+
+      raise MediaError, "Refusing to download from non-HTTPS URL: #{url}" unless uri.is_a?(URI::HTTPS)
+
+      unless allowed_host?(uri.host)
+        raise MediaError,
+          "Refusing to send credentials to non-allowlisted host: #{uri.host}"
+      end
+
+      uri
+    end
+
+    # Bypass-safe host check: exact match or a dotted subdomain of an allowed host.
+    # Rejects look-alikes such as "evil-fbsbx.com" or "fbsbx.com.attacker.com".
+    # @return [Boolean]
+    def allowed_host?(host)
+      return false if host.nil? || host.empty?
+
+      @media_host_allowlist.any? do |allowed|
+        host == allowed || host.end_with?(".#{allowed}")
+      end
+    end
+
+    # Streams the response body to disk in chunks rather than buffering it.
+    # @return [void]
+    def stream_to_file(response, save_to)
+      File.open(save_to, "wb") do |file|
+        response.body.each { |chunk| file.write(chunk) }
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/button/base.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class Button
+      # Shared behaviour for every button a template can declare.
+      #
+      # Each subclass owns its own wire type as `Defaults::TYPE` rather than having it
+      # supplied by the {Button::TYPES} registry — a button's type is intrinsic to the
+      # button, so keeping it on the class means one source of truth for both
+      # serialization and the per-type cap checks in {Component::Buttons}.
+      class Base
+        include ValueObject
+
+        # Character limit shared by every button that carries a tappable label.
+        MAX_TEXT_LENGTH = 25
+
+        # The uppercase value Meta expects in the button's `type` field.
+        # @return [String]
+        def api_type
+          self.class::Defaults::TYPE
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/button/copy_code.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class Button
+      # Copies a string — typically a coupon code — to the recipient's clipboard.
+      #
+      # Two things are unusual about this button: it carries no `text`, because Meta
+      # supplies and localises the label itself; and its `example` is a bare string
+      # rather than an array. At most one per template.
+      #
+      # In a limited-time-offer template the example is capped at 15 characters rather
+      # than 20, and the button must sit at index 0 — both enforced by {Template},
+      # which is the only place that can see the sibling components.
+      # Source: https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components/
+      class CopyCode < Base
+        module Defaults
+          TYPE = "COPY_CODE"
+          MAX_EXAMPLE_LENGTH = 20
+        end
+
+        # @!attribute [rw] example
+        #   @return [String]
+        attr_accessor :example
+
+        # @!attribute [rw] text
+        #   Always nil. Accepted only so a caller who supplies one gets told why it is
+        #   not allowed, rather than an opaque ArgumentError.
+        #   @return [nil]
+        attr_accessor :text
+
+        validates :example, presence: true, length: { maximum: Defaults::MAX_EXAMPLE_LENGTH }
+        validate :validate_no_text
+
+        # @param example [String] The code to copy (max 20 characters).
+        # @param text [String, nil] Not supported — Meta supplies the label.
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(example:, text: nil)
+          @example = example
+          @text = text
+
+          validate!
+        end
+
+        # @return [Hash] The serialized button.
+        def serialize
+          { type: Defaults::TYPE, example: }
+        end
+
+      private
+
+        # @return [void]
+        def validate_no_text
+          reject_unsupported(:text, "cannot be set on a copy-code button; Meta supplies the label")
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/button/otp/supported_app.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class Button
+      class Otp
+        # An Android app permitted to receive an autofilled one-time passcode.
+        #
+        # Required for the ONE_TAP and ZERO_TAP OTP types: Meta matches the delivering
+        # app against these entries before handing over the code.
+        # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/authentication-templates
+        class SupportedApp
+          include ValueObject
+
+          # @!attribute [rw] package_name
+          #   @return [String]
+          attr_accessor :package_name
+
+          # @!attribute [rw] signature_hash
+          #   @return [String]
+          attr_accessor :signature_hash
+
+          validates :package_name, presence: true
+          validates :signature_hash, presence: true
+
+          # @param package_name [String] The Android package name.
+          # @param signature_hash [String] The app's signing signature hash.
+          #  @raise [ActiveModel::ValidationError] if validation fails.
+          def initialize(package_name:, signature_hash:)
+            @package_name = package_name
+            @signature_hash = signature_hash
+
+            validate!
+          end
+
+          # @return [Hash] The serialized supported app.
+          def serialize
+            { package_name:, signature_hash: }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/button/otp.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class Button
+      # The one-time-passcode button that authentication templates are built around.
+      #
+      # Unlike every other button, its label is not settable: Meta supplies and
+      # localises both `text` and `autofill_text` per language. Passing either is
+      # therefore an error rather than something silently dropped.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/authentication-templates
+      class Otp < Base
+        module Defaults
+          TYPE = "OTP"
+        end
+
+        # How the recipient hands the code back to the business.
+        module OtpTypes
+          # Copies the code to the clipboard.
+          COPY_CODE = "COPY_CODE"
+          # Autofills the code into the requesting app.
+          ONE_TAP = "ONE_TAP"
+          # Delivers the code to a broadcast receiver with no user action.
+          ZERO_TAP = "ZERO_TAP"
+          # Renders no button at all.
+          NO_BUTTONS = "NO_BUTTONS"
+
+          ALL = [COPY_CODE, ONE_TAP, ZERO_TAP, NO_BUTTONS].freeze
+
+          # OTP types that hand the code to an app and so must declare which apps
+          # are allowed to receive it.
+          REQUIRING_SUPPORTED_APPS = [ONE_TAP, ZERO_TAP].freeze
+        end
+
+        # @!attribute [rw] otp_type
+        #   @return [String]
+        attr_accessor :otp_type
+
+        # @!attribute [rw] supported_apps
+        #   @return [Array<Otp::SupportedApp>]
+        attr_accessor :supported_apps
+
+        # @!attribute [rw] zero_tap_terms_accepted
+        #   @return [Boolean, nil]
+        attr_accessor :zero_tap_terms_accepted
+
+        # @!attribute [rw] text
+        #   Always nil — see the class comment.
+        #   @return [nil]
+        attr_accessor :text
+
+        # @!attribute [rw] autofill_text
+        #   Always nil — see the class comment.
+        #   @return [nil]
+        attr_accessor :autofill_text
+
+        validates :otp_type, presence: true, inclusion: { in: OtpTypes::ALL }
+        validate :validate_supported_apps
+        validate :validate_zero_tap_terms
+        validate :validate_no_labels
+
+        # @param otp_type [String, Symbol] One of {OtpTypes::ALL}, any casing.
+        # @param supported_apps [Array<Hash, Otp::SupportedApp>] Apps allowed to
+        #   receive the code. Required for ONE_TAP and ZERO_TAP.
+        # @param zero_tap_terms_accepted [Boolean, nil] Must be true for ZERO_TAP.
+        # @param text [String, nil] Not supported — Meta localises the label.
+        # @param autofill_text [String, nil] Not supported — Meta localises the label.
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(otp_type:, supported_apps: [], zero_tap_terms_accepted: nil, text: nil, autofill_text: nil)
+          @otp_type = normalize_otp_type(otp_type)
+          @supported_apps = build_supported_apps(supported_apps)
+          @zero_tap_terms_accepted = zero_tap_terms_accepted
+          @text = text
+          @autofill_text = autofill_text
+
+          validate!
+        end
+
+        # @return [Hash] The serialized button.
+        def serialize
+          {
+            type: Defaults::TYPE,
+            otp_type:,
+            supported_apps: serialized_supported_apps,
+            zero_tap_terms_accepted:,
+          }.compact
+        end
+
+      private
+
+        # Meta's docs are inconsistent about enum casing; accept either and emit
+        # uppercase, which is what responses come back as.
+        # @return [String, nil]
+        def normalize_otp_type(value)
+          return if value.nil?
+
+          candidate = value.to_s.upcase
+          OtpTypes::ALL.include?(candidate) ? candidate : value.to_s
+        end
+
+        # @return [Array<Otp::SupportedApp>]
+        # @raise [ActiveModel::ValidationError] if a supported app is invalid.
+        def build_supported_apps(apps)
+          Array(apps).map { |app| app.is_a?(SupportedApp) ? app : SupportedApp.new(**app) }
+        end
+
+        # @return [Array<Hash>, nil] nil when empty, so `compact` drops the key.
+        def serialized_supported_apps
+          return if supported_apps.empty?
+
+          supported_apps.map(&:serialize)
+        end
+
+        # @return [void]
+        def validate_supported_apps
+          return unless OtpTypes::REQUIRING_SUPPORTED_APPS.include?(otp_type)
+          return unless supported_apps.empty?
+
+          errors.add(:supported_apps, "can't be blank for the #{otp_type} OTP type")
+        end
+
+        # @return [void]
+        def validate_zero_tap_terms
+          return unless otp_type == OtpTypes::ZERO_TAP
+          return if zero_tap_terms_accepted == true
+
+          errors.add(:zero_tap_terms_accepted, "must be accepted for the ZERO_TAP OTP type")
+        end
+
+        # @return [void]
+        def validate_no_labels
+          reject_unsupported(:text, "cannot be set on an OTP button; Meta localises the label")
+          reject_unsupported(:autofill_text, "cannot be set on an OTP button; Meta localises the label")
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/button/phone_number.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class Button
+      # Places a phone call to the business when tapped.
+      #
+      # At most one per template. Meta may strip leading zeros that follow the country
+      # code, so store the number in full international form.
+      # Source: https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components/
+      class PhoneNumber < Base
+        module Defaults
+          TYPE = "PHONE_NUMBER"
+          MAX_PHONE_NUMBER_LENGTH = 20
+        end
+
+        # @!attribute [rw] text
+        #   @return [String]
+        attr_accessor :text
+
+        # @!attribute [rw] phone_number
+        #   @return [String]
+        attr_accessor :phone_number
+
+        validates :text, presence: true, length: { maximum: MAX_TEXT_LENGTH }
+        validates :phone_number, presence: true, length: { maximum: Defaults::MAX_PHONE_NUMBER_LENGTH }
+
+        # @param text [String] The button label (max 25 characters).
+        # @param phone_number [String] The number to call (max 20 characters).
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(text:, phone_number:)
+          @text = text
+          @phone_number = phone_number
+
+          validate!
+        end
+
+        # @return [Hash] The serialized button.
+        def serialize
+          { type: Defaults::TYPE, text:, phone_number: }
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/button/quick_reply.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class Button
+      # A tappable label that sends its own text back as a reply.
+      #
+      # The most common use is an opt-out ("Unsubscribe from Promos"), which Meta
+      # expects on marketing templates. Up to 10 per template, but they must be
+      # grouped contiguously — see {Component::Buttons}.
+      # Source: https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components/
+      class QuickReply < Base
+        module Defaults
+          TYPE = "QUICK_REPLY"
+        end
+
+        # @!attribute [rw] text
+        #   @return [String]
+        attr_accessor :text
+
+        validates :text, presence: true, length: { maximum: MAX_TEXT_LENGTH }
+
+        # @param text [String] The button label (max 25 characters).
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(text:)
+          @text = text
+
+          validate!
+        end
+
+        # @return [Hash] The serialized button.
+        def serialize
+          { type: Defaults::TYPE, text: }
+        end
+      end
+    end
+  end
+end