ruby-whatsapp 0.3.0

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class Button
+      # Opens a URL in the device's default browser.
+      #
+      # May carry a single variable, and only appended at the very end of the URL —
+      # Meta substitutes the send-side value there. Note the `example` here is a flat
+      # array *on the button*, unlike the header/body `example` object built by
+      # {Example}; that inconsistency is Meta's.
+      # Source: https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components/
+      class Url < Base
+        module Defaults
+          TYPE = "URL"
+          MAX_URL_LENGTH = 2000
+          MAX_VARIABLES = 1
+        end
+
+        # Matches a placeholder occupying the very end of the URL.
+        TRAILING_VARIABLE = /\{\{\s*\w+\s*\}\}\z/
+
+        # @!attribute [rw] text
+        #   @return [String]
+        attr_accessor :text
+
+        # @!attribute [rw] url
+        #   @return [String]
+        attr_accessor :url
+
+        # @!attribute [rw] example
+        #   @return [Array<String>, nil]
+        attr_accessor :example
+
+        validates :text, presence: true, length: { maximum: MAX_TEXT_LENGTH }
+        validates :url, presence: true, length: { maximum: Defaults::MAX_URL_LENGTH }
+        validate :validate_variable
+        validate :validate_example_present
+
+        # @param text [String] The button label (max 25 characters).
+        # @param url [String] The URL (max 2000 characters), optionally ending in a
+        #   single `{{1}}` or `{{name}}` placeholder.
+        # @param example [String, Array<String>, nil] A sample value for the
+        #   placeholder. Required when the URL has one.
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(text:, url:, example: nil)
+          @text = text
+          @url = url
+          @example = normalize_example(example)
+
+          validate!
+        end
+
+        # @return [Hash] The serialized button.
+        def serialize
+          {
+            type: Defaults::TYPE,
+            text:,
+            url:,
+            example:,
+          }.compact
+        end
+
+      private
+
+        # @return [Array<String>, nil]
+        def normalize_example(value)
+          return if blank_value?(value)
+
+          value.is_a?(Array) ? value : [value]
+        end
+
+        # @return [Boolean] Whether the URL declares a placeholder.
+        def variable?
+          Placeholders.occurrences(url).positive?
+        end
+
+        # A URL may carry at most one variable, and it must be the trailing segment.
+        #
+        # Counted by occurrence, not by unique name: `.../{{1}}/details/{{1}}` ends in a
+        # placeholder and names only one parameter, but the leading one still sits
+        # mid-URL, which is exactly what Meta forbids.
+        # @return [void]
+        def validate_variable
+          return if blank_value?(url)
+
+          count = Placeholders.occurrences(url)
+          return if count.zero?
+
+          if count > Defaults::MAX_VARIABLES
+            errors.add(:url, "supports at most one variable, found #{count}")
+            return
+          end
+
+          return if url.match?(TRAILING_VARIABLE)
+
+          errors.add(:url, "variable must be at the end of the URL")
+        end
+
+        # @return [void]
+        def validate_example_present
+          return if blank_value?(url) || !variable?
+          return unless blank_value?(example)
+
+          errors.add(:example, "can't be blank when the URL contains a variable")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    # Resolves a button kind to its implementing class.
+    #
+    # Resolution goes through the frozen {TYPES} whitelist — never `const_get` on
+    # caller input — so an unknown or hostile `type` can only raise, never resolve an
+    # arbitrary constant. Mirrors {Whatsapp::Messages::KINDS} and
+    # {Whatsapp::Messages::Interactive::ACTION_TYPES}.
+    #
+    # Only the button types with a published schema are registered. Meta's Graph API
+    # enum also lists FLOW, MPM, CATALOG, VOICE_CALL, VIDEO_CALL, POSTBACK,
+    # BOOKING_STATUS, PAYMENT_REQUEST and REQUEST_CONTACT_INFO, but publishes no
+    # field reference for them, so they are deliberately absent rather than guessed.
+    # Source: https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components/
+    class Button
+      TYPES = {
+        quick_reply: QuickReply,
+        url: Url,
+        phone_number: PhoneNumber,
+        copy_code: CopyCode,
+        otp: Otp,
+      }.freeze
+
+      class << self
+        # @param type [Symbol, String] The button kind, in either casing
+        #   (`:quick_reply`, `"quick_reply"`, or Meta's `"QUICK_REPLY"`).
+        # @param attrs [Hash] Forwarded to the resolved button class.
+        # @return [Button::Base]
+        # @raise [TemplateError] if the type is unknown.
+        # @raise [ActiveModel::ValidationError] if the button is invalid.
+        def build(type:, **attrs)
+          klass = TYPES.fetch(normalize(type)) do
+            raise TemplateError,
+              "Unknown button type: #{type.inspect}. Known types: #{TYPES.keys.join(', ')}"
+          end
+
+          klass.new(**attrs)
+        end
+
+        # Builds and serializes in one step.
+        # @return [Hash]
+        def serialize(type:, **attrs)
+          build(type:, **attrs).serialize
+        end
+
+        # @param type [Symbol, String]
+        # @return [Symbol] The registry key for the given type.
+        def normalize(type)
+          type.to_s.downcase.to_sym
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/categories.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    # The three categories every template must declare.
+    #
+    # The choice is not cosmetic: it drives pricing, it decides which components are
+    # legal, and Meta validates it against the template's actual content — a mismatch
+    # comes back as REJECTED with the reason INCORRECT_CATEGORY.
+    #
+    # Shared by {Template}, {ComponentSet} and {LibraryTemplate}, hence its own file
+    # rather than living on any one of them.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/template-categorization
+    module Categories
+      # Identity verification with one-time passcodes. No URLs, media, or emojis, and
+      # parameters are capped at 15 characters.
+      AUTHENTICATION = "AUTHENTICATION"
+      # Promotions, awareness, retargeting. Anything ambiguous lands here.
+      MARKETING = "MARKETING"
+      # Transactional and non-promotional: order, account, or transaction updates, or
+      # genuinely essential notices.
+      UTILITY = "UTILITY"
+
+      ALL = [AUTHENTICATION, MARKETING, UTILITY].freeze
+
+      # Normalizes caller input to a canonical uppercase category.
+      #
+      # Meta's own docs are inconsistent about enum casing, so callers may reasonably
+      # pass `:marketing`, `"marketing"`, or `"MARKETING"`. Unrecognized values are
+      # returned untouched so validations can report them.
+      # @param value [String, Symbol, nil]
+      # @return [String, nil]
+      def self.normalize(value)
+        return if value.nil?
+
+        candidate = value.to_s.upcase
+        ALL.include?(candidate) ? candidate : value.to_s
+      end
+
+      # @param value [String, Symbol, nil]
+      # @return [Boolean]
+      def self.valid?(value)
+        ALL.include?(normalize(value))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class Component
+      # Shared behaviour for every component a template can declare.
+      #
+      # Holds the template's `parameter_format`, which every component accepts even
+      # though only {Header} and {Body} use it. Uniformity is deliberate: {Component
+      # .build} can then thread the format down without knowing which components care,
+      # and carousel cards can pass it on to their own nested components.
+      #
+      # Each subclass owns its wire type as `Defaults::TYPE`, so the {Component::TYPES}
+      # registry maps kind to class only and there is one source of truth.
+      class Base
+        include ValueObject
+
+        # @!attribute [rw] parameter_format
+        #   @return [String] see {ParameterFormats}.
+        attr_accessor :parameter_format
+
+        # @!attribute [r] example_error
+        #   Set when the caller's example values could not be interpreted. See
+        #   {#build_example_payload}.
+        #   @return [String, nil]
+        attr_reader :example_error
+
+        validate :validate_example_shape
+
+        # @param parameter_format [String, Symbol] The owning template's placeholder
+        #   style. Defaults to Meta's own default.
+        def initialize(parameter_format: ParameterFormats::POSITIONAL)
+          @parameter_format = ParameterFormats.normalize(parameter_format)
+        end
+
+        # The uppercase value Meta expects in the component's `type` field.
+        # @return [String]
+        def api_type
+          self.class::Defaults::TYPE
+        end
+
+      protected
+
+        # Builds an example payload, deferring any shape mismatch to validation.
+        #
+        # {Example.serialize} raises ArgumentError when the values contradict the
+        # parameter format (a Hash of names under POSITIONAL, say). Letting that escape
+        # `initialize` would bypass the validation layer every other failure goes
+        # through, leaving callers to handle two error types for one kind of mistake.
+        # It is captured here and re-reported by {#validate_example_shape}.
+        # @param role [Symbol] `:header` or `:body`.
+        # @param values [Array, Hash, String, nil]
+        # @return [Hash, nil]
+        def build_example_payload(role:, values:)
+          Example.serialize(role:, parameter_format:, values:)
+        rescue ArgumentError => e
+          @example_error = e.message
+          nil
+        end
+
+        # Validates that text placeholders are well-formed and consistent with the
+        # template's parameter format.
+        #
+        # Shared by {Header} and {Body} — the two components that accept placeholders —
+        # because the three failure modes (mixed styles, a positional run that does not
+        # start at 1, and a style that contradicts the template) are identical for both
+        # and are among the most common causes of a rejected template.
+        # @param text [String, nil]
+        # @return [void]
+        def validate_placeholder_style(text)
+          return if blank_value?(text)
+
+          style = Placeholders.style(text)
+          return if style.nil?
+
+          return errors.add(:text, "cannot mix positional and named placeholders") if style == :mixed
+          return validate_named_style if style == :named
+
+          validate_positional_style(text)
+        end
+
+      private
+
+        # @return [void]
+        def validate_example_shape
+          errors.add(:example, example_error) unless example_error.nil?
+        end
+
+        # @return [void]
+        def validate_named_style
+          return if ParameterFormats.named?(parameter_format)
+
+          errors.add(:text,
+            "uses named placeholders but the template parameter_format is " \
+              "#{ParameterFormats::POSITIONAL}")
+        end
+
+        # @return [void]
+        def validate_positional_style(text)
+          if ParameterFormats.named?(parameter_format)
+            return errors.add(:text,
+              "uses positional placeholders but the template parameter_format is #{ParameterFormats::NAMED}")
+          end
+
+          return if Placeholders.sequential?(text)
+
+          errors.add(:text, "positional placeholders must start at {{1}} and increment without gaps")
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/component/body.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class Component
+      # The template's message text. The only component Meta requires.
+      #
+      # Two mutually exclusive shapes, hence the XOR validation:
+      #
+      #   standard       — `text` (1024 chars) with any number of placeholders, plus a
+      #                    matching `example`
+      #   authentication — no text at all. Meta supplies the fixed, localised string
+      #                    "<VERIFICATION_CODE> is your verification code." and
+      #                    `add_security_recommendation` only decides whether the
+      #                    "do not share this code" line is appended.
+      #
+      # The tighter 600-character limit that applies inside a limited-time-offer
+      # template is enforced by {Template}, which is the only object that can see
+      # whether such a component is present.
+      # Source: https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components/
+      class Body < Base
+        module Defaults
+          TYPE = "BODY"
+          MAX_TEXT_LENGTH = 1024
+        end
+
+        # @!attribute [rw] text
+        #   @return [String, nil]
+        attr_accessor :text
+
+        # @!attribute [rw] example
+        #   @return [Hash, nil] The serialized example payload.
+        attr_accessor :example
+
+        # @!attribute [rw] add_security_recommendation
+        #   @return [Boolean, nil] Authentication templates only.
+        attr_accessor :add_security_recommendation
+
+        # @!attribute [rw] example_values
+        #   The raw example input, kept so the placeholder/example counts can be
+        #   compared without re-parsing the serialized payload.
+        #   @return [Array, Hash, String, nil]
+        attr_accessor :example_values
+
+        validate :validate_shape
+        validate :validate_text
+        validate :validate_example
+
+        # @param text [String, nil] The body text (max 1024 characters).
+        # @param example [Array, Hash, String, nil] Sample values for the placeholders,
+        #   or a pre-built example payload.
+        # @param add_security_recommendation [Boolean, nil] Authentication templates
+        #   only; mutually exclusive with `text`.
+        # @param kwargs [Hash] Forwarded to {Base} (`parameter_format`).
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(text: nil, example: nil, add_security_recommendation: nil, **)
+          super(**)
+
+          @text = text
+          @add_security_recommendation = add_security_recommendation
+          @example_values = example
+          @example = build_example_payload(role: :body, values: example)
+
+          validate!
+        end
+
+        # @return [Boolean] Whether this is the flag-based authentication shape.
+        def authentication?
+          !add_security_recommendation.nil?
+        end
+
+        # @return [Hash] The serialized component.
+        def serialize
+          return { type: Defaults::TYPE, add_security_recommendation: } if authentication?
+
+          {
+            type: Defaults::TYPE,
+            text:,
+            example:,
+          }.compact
+        end
+
+      private
+
+        # @return [void]
+        def validate_shape
+          return unless authentication? && !blank_value?(text)
+
+          errors.add(:text, "cannot be combined with add_security_recommendation")
+        end
+
+        # @return [void]
+        def validate_text
+          return if authentication?
+          return errors.add(:text, "can't be blank") if blank_value?(text)
+
+          if text.length > Defaults::MAX_TEXT_LENGTH
+            errors.add(:text, "is too long (maximum is #{Defaults::MAX_TEXT_LENGTH} characters)")
+          end
+
+          validate_placeholder_style(text)
+        end
+
+        # The number of examples must match the number of placeholders exactly — a
+        # mismatch is one of the most common causes of a rejected template.
+        # @return [void]
+        def validate_example
+          # A shape mismatch is already reported by validate_example_shape, and
+          # Example.count would raise on the same input.
+          return if authentication? || blank_value?(text) || !example_error.nil?
+
+          expected = Placeholders.count(text)
+          return if expected.zero? && blank_value?(example)
+
+          if blank_value?(example)
+            return errors.add(:example,
+              "can't be blank when the body text contains placeholders")
+          end
+
+          actual = Example.count(role: :body, parameter_format:, values: example_values)
+          return if actual == expected
+
+          errors.add(:example, count_mismatch_message(expected, actual))
+        end
+
+        # @return [String]
+        def count_mismatch_message(expected, actual)
+          "does not match the body text: #{expected} #{pluralize(expected, 'placeholder')} " \
+            "but #{actual} #{pluralize(actual, 'example')}"
+        end
+
+        # @return [String]
+        def pluralize(count, word)
+          count == 1 ? word : "#{word}s"
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/component/buttons.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class Component
+      # The container for a template's tappable buttons. At most one per template,
+      # holding up to 10 buttons.
+      #
+      # Note the asymmetry with the send side: here every button lives inside this one
+      # component, whereas sending a template emits one `button` component per button,
+      # addressed by a zero-based `index` that follows the order declared here. That is
+      # why {#serialize} preserves the caller's order exactly.
+      # Source: https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components/
+      class Buttons < Base
+        module Defaults
+          TYPE = "BUTTONS"
+          MAX_BUTTONS = 10
+        end
+
+        # Documented per-type caps. Only the limits Meta actually publishes are
+        # enforced; OTP is deliberately uncapped here (the overall MAX_BUTTONS still
+        # applies) because no per-type limit is stated for it.
+        MAX_PER_TYPE = {
+          Button::QuickReply::Defaults::TYPE => 10,
+          Button::Url::Defaults::TYPE => 2,
+          Button::PhoneNumber::Defaults::TYPE => 1,
+          Button::CopyCode::Defaults::TYPE => 1,
+        }.freeze
+
+        # @!attribute [rw] buttons
+        #   @return [Array<Button::Base>]
+        attr_accessor :buttons
+
+        validates :buttons, presence: true, length: { maximum: Defaults::MAX_BUTTONS }
+        validate :validate_per_type_caps
+        validate :validate_quick_reply_grouping
+
+        # @param buttons [Array<Hash, Button::Base>] The buttons, in display order.
+        # @param kwargs [Hash] Forwarded to {Base} (`parameter_format`).
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(buttons: [], **)
+          super(**)
+
+          @buttons = build_buttons(buttons)
+
+          validate!
+        end
+
+        # The wire types in declared order. Exposed so {Carousel} can compare card
+        # structures and {Template} can inspect buttons across components.
+        # @return [Array<String>]
+        def api_types
+          buttons.map(&:api_type)
+        end
+
+        # @return [Hash] The serialized component.
+        def serialize
+          { type: Defaults::TYPE, buttons: buttons.map(&:serialize) }
+        end
+
+      private
+
+        # @return [Array<Button::Base>]
+        # @raise [ActiveModel::ValidationError] if a button is invalid.
+        # @raise [TemplateError] if a button type is unknown.
+        def build_buttons(list)
+          Array(list).map { |button| button.is_a?(Button::Base) ? button : Button.build(**button) }
+        end
+
+        # @return [void]
+        def validate_per_type_caps
+          api_types.tally.each do |type, count|
+            maximum = MAX_PER_TYPE[type]
+            next if maximum.nil? || count <= maximum
+
+            errors.add(:buttons, "allow at most #{maximum} #{type} #{maximum == 1 ? 'button' : 'buttons'}")
+          end
+        end
+
+        # Meta rejects a payload whose quick-reply buttons are interrupted by another
+        # type: `[QR, URL, QR]` is invalid while `[QR, QR, URL]` and `[URL, QR, QR]`
+        # are both fine. The check is therefore "do their indexes form one unbroken
+        # run", not "are they first or last".
+        # @return [void]
+        def validate_quick_reply_grouping
+          indexes = api_types.each_index.select { |i| api_types[i] == Button::QuickReply::Defaults::TYPE }
+          return if indexes.size <= 1
+          return if indexes.last - indexes.first == indexes.size - 1
+
+          errors.add(:buttons, "quick reply buttons must be grouped together, without other types between them")
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/component/carousel/card.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class Component
+      class Carousel
+        # One card in a carousel: a required media header, an optional body, and up to
+        # two buttons.
+        #
+        # Composes {Component::Header} and {Component::Buttons} rather than restating
+        # their rules — the only extra constraint is that a card's header must be image
+        # or video, since a carousel card cannot be text or a location.
+        #
+        # Note there is no `card_index` here. Cards are positional at creation time;
+        # the zero-based `card_index` only appears when sending a message.
+        # Source: https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/carousel-templates
+        class Card
+          include ValueObject
+
+          module Defaults
+            MAX_BUTTONS = 2
+          end
+
+          # A carousel card's header is restricted to these formats.
+          ALLOWED_HEADER_FORMATS = [Header::Formats::IMAGE, Header::Formats::VIDEO].freeze
+
+          # @!attribute [rw] header
+          #   @return [Component::Header]
+          attr_accessor :header
+
+          # @!attribute [rw] body
+          #   @return [Component::Body, nil]
+          attr_accessor :body
+
+          # @!attribute [rw] buttons
+          #   @return [Component::Buttons, nil]
+          attr_accessor :buttons
+
+          validates :header, presence: true
+          validate :validate_header_format
+          validate :validate_button_count
+
+          # @param header [Hash, Component::Header] The card's media header.
+          # @param body [Hash, Component::Body, nil] The card's body.
+          # @param buttons [Array<Hash, Button::Base>, nil] Up to 2 buttons.
+          # @param parameter_format [String, Symbol] The owning template's placeholder
+          #   style, threaded into the card's own components.
+          #  @raise [ActiveModel::ValidationError] if validation fails.
+          def initialize(header:, body: nil, buttons: nil, parameter_format: ParameterFormats::POSITIONAL)
+            @parameter_format = ParameterFormats.normalize(parameter_format)
+            @header = build(Header, header)
+            @body = build(Body, body)
+            @buttons = blank_value?(buttons) ? nil : Buttons.new(buttons:, parameter_format: @parameter_format)
+
+            validate!
+          end
+
+          # A comparable description of the card's shape, used by {Carousel} to enforce
+          # Meta's "all cards must have the same components" rule. Content is
+          # deliberately excluded — only structure matters.
+          # @return [Array]
+          def signature
+            [header&.format, !body.nil?, buttons&.api_types]
+          end
+
+          # @return [Hash] The serialized card.
+          def serialize
+            { components: [header, body, buttons].compact.map(&:serialize) }
+          end
+
+        private
+
+          # @return [Component::Base, nil]
+          def build(klass, value)
+            return if blank_value?(value)
+            return value if value.is_a?(klass)
+
+            klass.new(**value, parameter_format: @parameter_format)
+          end
+
+          # @return [void]
+          def validate_header_format
+            return if header.nil?
+            return if ALLOWED_HEADER_FORMATS.include?(header.format)
+
+            errors.add(:header, "format must be IMAGE or VIDEO for a carousel card, got #{header.format}")
+          end
+
+          # @return [void]
+          def validate_button_count
+            return if buttons.nil?
+            return if buttons.buttons.size <= Defaults::MAX_BUTTONS
+
+            errors.add(:buttons, "allow at most #{Defaults::MAX_BUTTONS} buttons per carousel card")
+          end
+        end
+      end
+    end
+  end
+end