ruby-whatsapp 0.3.0

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class Component
+      # A horizontally scrollable set of 2 to 10 cards, each with its own media header
+      # and buttons. Marketing templates only, which {Template} enforces.
+      #
+      # The card count is fixed at creation: an approved carousel template must be sent
+      # with exactly the number of cards it was created with.
+      #
+      # Every card must share the same structure — same header format, same button
+      # types, and body text either on all of them or none. Meta's stated reason for
+      # the body rule is keeping card heights consistent. {Card#signature} is what makes
+      # this checkable.
+      # Source: https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/carousel-templates
+      class Carousel < Base
+        module Defaults
+          TYPE = "CAROUSEL"
+          MIN_CARDS = 2
+          MAX_CARDS = 10
+        end
+
+        # @!attribute [rw] cards
+        #   @return [Array<Carousel::Card>]
+        attr_accessor :cards
+
+        validates :cards, presence: true,
+          length: { minimum: Defaults::MIN_CARDS, maximum: Defaults::MAX_CARDS }
+        validate :validate_identical_structure
+
+        # @param cards [Array<Hash, Carousel::Card>] Between 2 and 10 cards.
+        # @param kwargs [Hash] Forwarded to {Base} (`parameter_format`).
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(cards: [], **)
+          super(**)
+
+          @cards = build_cards(cards)
+
+          validate!
+        end
+
+        # @return [Hash] The serialized component.
+        def serialize
+          { type: Defaults::TYPE, cards: cards.map(&:serialize) }
+        end
+
+      private
+
+        # @return [Array<Carousel::Card>]
+        # @raise [ActiveModel::ValidationError] if a card is invalid.
+        def build_cards(list)
+          Array(list).map do |card|
+            card.is_a?(Card) ? card : Card.new(**card, parameter_format:)
+          end
+        end
+
+        # @return [void]
+        def validate_identical_structure
+          return if cards.size < 2
+
+          signatures = cards.map(&:signature).uniq
+          return if signatures.size == 1
+
+          errors.add(:cards, "must all have an identical structure: same header format, same button types, " \
+            "and body text on either every card or none")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class Component
+      # The optional small-print line below the body. At most one per template.
+      #
+      # Two mutually exclusive shapes, mirroring {Body}:
+      #
+      #   standard       — `text` (60 chars, and no placeholders at all)
+      #   authentication — `code_expiration_minutes`, which renders Meta's own
+      #                    localised "This code expires in N minutes." Omit the footer
+      #                    entirely to omit that notice.
+      #
+      # Forbidden altogether in limited-time-offer templates, which {Template} enforces.
+      # Source: https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components/
+      class Footer < Base
+        module Defaults
+          TYPE = "FOOTER"
+          MAX_TEXT_LENGTH = 60
+          CODE_EXPIRATION_RANGE = (1..90)
+        end
+
+        # @!attribute [rw] text
+        #   @return [String, nil]
+        attr_accessor :text
+
+        # @!attribute [rw] code_expiration_minutes
+        #   @return [Integer, nil] Authentication templates only.
+        attr_accessor :code_expiration_minutes
+
+        validate :validate_shape
+        validate :validate_text
+        validate :validate_code_expiration
+
+        # @param text [String, nil] The footer text (max 60 characters, no placeholders).
+        # @param code_expiration_minutes [Integer, nil] Authentication templates only;
+        #   must be within 1..90. Mutually exclusive with `text`.
+        # @param kwargs [Hash] Forwarded to {Base} (`parameter_format`).
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(text: nil, code_expiration_minutes: nil, **)
+          super(**)
+
+          @text = text
+          @code_expiration_minutes = code_expiration_minutes
+
+          validate!
+        end
+
+        # @return [Boolean] Whether this is the expiry-based authentication shape.
+        def authentication?
+          !code_expiration_minutes.nil?
+        end
+
+        # @return [Hash] The serialized component.
+        def serialize
+          return { type: Defaults::TYPE, code_expiration_minutes: } if authentication?
+
+          { type: Defaults::TYPE, text: }
+        end
+
+      private
+
+        # @return [void]
+        def validate_shape
+          if authentication? && !blank_value?(text)
+            return errors.add(:text, "cannot be combined with code_expiration_minutes")
+          end
+
+          return unless blank_value?(text) && !authentication?
+
+          errors.add(:base, "requires either text or code_expiration_minutes")
+        end
+
+        # @return [void]
+        def validate_text
+          return if authentication? || blank_value?(text)
+
+          if text.length > Defaults::MAX_TEXT_LENGTH
+            errors.add(:text, "is too long (maximum is #{Defaults::MAX_TEXT_LENGTH} characters)")
+          end
+
+          return if Placeholders.count(text).zero?
+
+          errors.add(:text, "does not support placeholders")
+        end
+
+        # @return [void]
+        def validate_code_expiration
+          return unless authentication?
+          return if code_expiration_minutes.is_a?(Integer) &&
+            Defaults::CODE_EXPIRATION_RANGE.cover?(code_expiration_minutes)
+
+          errors.add(:code_expiration_minutes, "must be in #{Defaults::CODE_EXPIRATION_RANGE}")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class Component
+      # The optional component above the body: a line of text, a media attachment, or
+      # a location pin. At most one per template.
+      #
+      # Three shapes share one class because they all serialize to the same
+      # `{type:, format:, ...}` envelope and differ only in which fields are legal.
+      # The `format` decides:
+      #
+      #   TEXT     — `text` (60 chars, at most ONE placeholder) plus an `example`
+      #   media    — `header_handle` from the Resumable Upload API; no text
+      #   LOCATION — nothing else; coordinates are supplied when the message is sent
+      #
+      # This mirrors the conditional-validation approach already used by
+      # {Whatsapp::Messages::Video} for its id-or-link choice.
+      # Source: https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components/
+      class Header < Base
+        module Defaults
+          TYPE = "HEADER"
+          MAX_TEXT_LENGTH = 60
+          MAX_VARIABLES = 1
+        end
+
+        module Formats
+          TEXT = "TEXT"
+          IMAGE = "IMAGE"
+          VIDEO = "VIDEO"
+          DOCUMENT = "DOCUMENT"
+          GIF = "GIF"
+          LOCATION = "LOCATION"
+
+          # Formats that carry an uploaded asset handle rather than text.
+          MEDIA = [IMAGE, VIDEO, DOCUMENT, GIF].freeze
+          ALL = [TEXT, *MEDIA, LOCATION].freeze
+        end
+
+        # Characters Meta rejects in a header, which does not support Markdown.
+        MARKDOWN_CHARACTERS = ["*", "_", "~", "`"].freeze
+
+        # @!attribute [rw] format
+        #   @return [String] one of {Formats::ALL}.
+        attr_accessor :format
+
+        # @!attribute [rw] text
+        #   @return [String, nil] TEXT headers only.
+        attr_accessor :text
+
+        # @!attribute [rw] example
+        #   @return [Hash, nil] The serialized example payload.
+        attr_accessor :example
+
+        # @!attribute [rw] header_handle
+        #   @return [String, Array<String>, nil] Media headers only.
+        attr_accessor :header_handle
+
+        validates :format, presence: true, inclusion: { in: Formats::ALL }
+        validate :validate_text_shape
+        validate :validate_media_shape
+        validate :validate_location_shape
+
+        # @param format [String, Symbol] one of {Formats::ALL}, any casing.
+        # @param text [String, nil] The header text, for the TEXT format.
+        # @param example [Array, Hash, String, nil] A sample value for the text
+        #   placeholder, or a pre-built example payload.
+        # @param header_handle [String, Array<String>, nil] The uploaded asset handle,
+        #   for media formats. A convenience alternative to
+        #   `example: { header_handle: [...] }`.
+        # @param kwargs [Hash] Forwarded to {Base} (`parameter_format`).
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(format:, text: nil, example: nil, header_handle: nil, **)
+          super(**)
+
+          @format = normalize_format(format)
+          @text = text
+          @header_handle = header_handle
+          @example = build_example(example)
+
+          validate!
+        end
+
+        # @return [Boolean] Whether this header carries an uploaded asset.
+        def media?
+          Formats::MEDIA.include?(format)
+        end
+
+        # @return [Hash] The serialized component.
+        def serialize
+          {
+            type: Defaults::TYPE,
+            format:,
+            text:,
+            example:,
+          }.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_format(value)
+          return if value.nil?
+
+          candidate = value.to_s.upcase
+          Formats::ALL.include?(candidate) ? candidate : value.to_s
+        end
+
+        # Builds the example payload from whichever input the caller used.
+        # @return [Hash, nil]
+        def build_example(value)
+          return { header_handle: Array(header_handle) } unless blank_value?(header_handle)
+
+          build_example_payload(role: :header, values: value)
+        end
+
+        # @return [void]
+        def validate_text_shape
+          return unless format == Formats::TEXT
+
+          reject_unsupported(:header_handle, "cannot be set on a #{Formats::TEXT} header")
+          validate_text_presence_and_length
+          validate_text_variables
+          validate_placeholder_style(text)
+          validate_no_markdown
+        end
+
+        # @return [void]
+        def validate_text_presence_and_length
+          return errors.add(:text, "can't be blank") if blank_value?(text)
+          return if text.length <= Defaults::MAX_TEXT_LENGTH
+
+          errors.add(:text, "is too long (maximum is #{Defaults::MAX_TEXT_LENGTH} characters)")
+        end
+
+        # A text header supports at most one placeholder, and needs an example for it.
+        # @return [void]
+        def validate_text_variables
+          count = Placeholders.count(text)
+          return if count.zero?
+
+          if count > Defaults::MAX_VARIABLES
+            errors.add(:text, "supports at most one variable, found #{count}")
+            return
+          end
+
+          errors.add(:example, "can't be blank when the header text contains a variable") if blank_value?(example)
+        end
+
+        # Checks only the literal text, with placeholders removed first.
+        #
+        # Named placeholders are lowercase-and-underscores by definition, so scanning
+        # the raw text would reject `{{sale_start_date}}` for containing an underscore
+        # and make named parameters unusable in a text header.
+        # @return [void]
+        def validate_no_markdown
+          return if blank_value?(text)
+
+          literal = text.gsub(Placeholders::PATTERN, "")
+          found = MARKDOWN_CHARACTERS.select { |char| literal.include?(char) }
+          return if found.empty?
+
+          errors.add(:text, "cannot contain Markdown characters (found #{found.join(' ')})")
+        end
+
+        # @return [void]
+        def validate_media_shape
+          return unless media?
+
+          reject_unsupported(:text, "cannot be set on a #{format} header")
+          return unless blank_value?(example)
+
+          errors.add(:header_handle, "can't be blank for a #{format} header")
+        end
+
+        # @return [void]
+        def validate_location_shape
+          return unless format == Formats::LOCATION
+
+          reject_unsupported(:text, "cannot be set on a #{Formats::LOCATION} header")
+          reject_unsupported(:header_handle, "cannot be set on a #{Formats::LOCATION} header")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class Component
+      # The offer banner that turns a marketing template into a limited-time offer,
+      # optionally with a live countdown timer.
+      #
+      # Its presence changes the rules for the rest of the template: a footer becomes
+      # forbidden, the body drops to 600 characters, the header narrows to image or
+      # video, and the category must be MARKETING. Those are all cross-component rules,
+      # so {Template} enforces them.
+      #
+      # The expiry timestamp itself is *not* set here — it is supplied per message when
+      # sending, as `expiration_time_ms`. This component only declares that the
+      # template has one.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/limited-time-offer-templates
+      class LimitedTimeOffer < Base
+        module Defaults
+          TYPE = "LIMITED_TIME_OFFER"
+          MAX_TEXT_LENGTH = 16
+        end
+
+        # @!attribute [rw] text
+        #   @return [String]
+        attr_accessor :text
+
+        # @!attribute [rw] has_expiration
+        #   @return [Boolean, nil]
+        attr_accessor :has_expiration
+
+        validates :text, presence: true, length: { maximum: Defaults::MAX_TEXT_LENGTH }
+
+        # @param text [String] The offer label (max 16 characters).
+        # @param has_expiration [Boolean, nil] Whether to show a countdown timer.
+        # @param kwargs [Hash] Forwarded to {Base} (`parameter_format`).
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(text:, has_expiration: nil, **)
+          super(**)
+
+          @text = text
+          @has_expiration = has_expiration
+
+          validate!
+        end
+
+        # @return [Hash] The serialized component.
+        def serialize
+          {
+            type: Defaults::TYPE,
+            limited_time_offer: { text:, has_expiration: }.compact,
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    # Resolves a component 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 {Button::TYPES}.
+    #
+    # Only the component types with a published schema are registered. Meta's Graph API
+    # enum also lists GREETING, ALBUM, CALL_PERMISSION_REQUEST, TAP_TARGET_CONFIGURATION
+    # and ATTACHMENT, but publishes no field reference for them, so they are
+    # deliberately absent rather than guessed.
+    #
+    # Note that a component validates only *itself* here. Rules that span components —
+    # a footer being forbidden alongside a limited-time offer, a carousel implying the
+    # MARKETING category — live on {Template}, which is the only object that can see
+    # all the siblings.
+    # Source: https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components/
+    class Component
+      TYPES = {
+        header: Header,
+        body: Body,
+        footer: Footer,
+        buttons: Buttons,
+        carousel: Carousel,
+        limited_time_offer: LimitedTimeOffer,
+      }.freeze
+
+      class << self
+        # @param type [Symbol, String] The component kind, in either casing
+        #   (`:body`, `"body"`, or Meta's `"BODY"`).
+        # @param attrs [Hash] Forwarded to the resolved component class, including the
+        #   owning template's `parameter_format`.
+        # @return [Component::Base]
+        # @raise [TemplateError] if the type is unknown.
+        # @raise [ActiveModel::ValidationError] if the component is invalid.
+        def build(type:, **attrs)
+          klass = TYPES.fetch(normalize(type)) do
+            raise TemplateError,
+              "Unknown component 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/component_set.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    # A template's components, plus every rule that spans more than one of them.
+    #
+    # This is the other half of the split described in {Component}: a component class
+    # validates itself, and everything about how components *relate* lives here. That
+    # keeps rules like "a footer is forbidden alongside a limited-time offer" in one
+    # place instead of duplicated across the sibling classes that would each only see
+    # half the picture.
+    #
+    # It is a separate object from {Template} because editing a template replaces its
+    # components wholesale without re-supplying a name or language, so `update` needs
+    # exactly these checks and none of the template-identity ones.
+    #
+    # `category` is optional for that reason: when it is absent — as when editing — the
+    # category-dependent rules are skipped rather than guessed at.
+    class ComponentSet
+      include ValueObject
+
+      module Defaults
+        # A limited-time-offer template caps the body well below the usual 1024.
+        LIMITED_TIME_OFFER_MAX_BODY_LENGTH = 600
+        # ...and its copy-code button below the usual 20.
+        LIMITED_TIME_OFFER_MAX_COPY_CODE_LENGTH = 15
+      end
+
+      # Wire types that may appear at most once in a template.
+      SINGLETON_TYPES = [
+        Component::Header::Defaults::TYPE,
+        Component::Footer::Defaults::TYPE,
+        Component::Buttons::Defaults::TYPE,
+        Component::Carousel::Defaults::TYPE,
+        Component::LimitedTimeOffer::Defaults::TYPE,
+      ].freeze
+
+      # Components restricted to a subset of categories, and which ones.
+      CATEGORY_RESTRICTED_TYPES = {
+        Component::Carousel::Defaults::TYPE => [Categories::MARKETING].freeze,
+        Component::LimitedTimeOffer::Defaults::TYPE => [Categories::MARKETING].freeze,
+      }.freeze
+
+      # Header formats a limited-time-offer template may use.
+      LIMITED_TIME_OFFER_HEADER_FORMATS = [
+        Component::Header::Formats::IMAGE,
+        Component::Header::Formats::VIDEO,
+      ].freeze
+
+      # Categories that may use a location header.
+      LOCATION_HEADER_CATEGORIES = [Categories::UTILITY, Categories::MARKETING].freeze
+
+      # @!attribute [rw] components
+      #   @return [Array<Component::Base>]
+      attr_accessor :components
+
+      # @!attribute [rw] category
+      #   @return [String, nil]
+      attr_accessor :category
+
+      # @!attribute [rw] parameter_format
+      #   @return [String]
+      attr_accessor :parameter_format
+
+      validates :components, presence: true
+      validate :validate_body_count
+      validate :validate_singletons
+      validate :validate_category_restrictions
+      validate :validate_location_header
+      validate :validate_limited_time_offer
+
+      # @param components [Array<Hash, Component::Base>] The template's components.
+      # @param category [String, Symbol, nil] The owning template's category. Omit to
+      #   skip the category-dependent rules.
+      # @param parameter_format [String, Symbol] The placeholder style, threaded into
+      #   every component.
+      #  @raise [ActiveModel::ValidationError] if validation fails.
+      #  @raise [TemplateError] if a component type is unknown.
+      def initialize(components:, category: nil, parameter_format: ParameterFormats::POSITIONAL)
+        @category = Categories.normalize(category)
+        @parameter_format = ParameterFormats.normalize(parameter_format)
+        @components = build_components(components)
+
+        validate!
+      end
+
+      # @param api_type [String] A component wire type, e.g. `"BODY"`.
+      # @return [Component::Base, nil]
+      def find(api_type)
+        components.find { |component| component.api_type == api_type }
+      end
+
+      # @return [Array<String>] The wire types present, in declared order.
+      def api_types
+        components.map(&:api_type)
+      end
+
+      # @return [Array<Hash>] The serialized components.
+      def serialize
+        components.map(&:serialize)
+      end
+
+    private
+
+      # @return [Array<Component::Base>]
+      def build_components(list)
+        Array(list).map do |component|
+          next component if component.is_a?(Component::Base)
+
+          Component.build(**component, parameter_format:)
+        end
+      end
+
+      # @return [void]
+      def validate_body_count
+        return if api_types.count(Component::Body::Defaults::TYPE) == 1
+
+        errors.add(:components, "requires exactly one BODY component")
+      end
+
+      # @return [void]
+      def validate_singletons
+        SINGLETON_TYPES.each do |type|
+          next if api_types.count(type) <= 1
+
+          errors.add(:components, "allow at most one #{type} component")
+        end
+      end
+
+      # @return [void]
+      def validate_category_restrictions
+        return if category.nil?
+
+        CATEGORY_RESTRICTED_TYPES.each do |type, allowed|
+          next unless api_types.include?(type)
+          next if allowed.include?(category)
+
+          errors.add(:components, "#{type} is only supported on #{allowed.join('/')} templates, not #{category}")
+        end
+      end
+
+      # @return [void]
+      def validate_location_header
+        return if category.nil?
+
+        header = find(Component::Header::Defaults::TYPE)
+        return unless header&.format == Component::Header::Formats::LOCATION
+        return if LOCATION_HEADER_CATEGORIES.include?(category)
+
+        errors.add(:components,
+          "a LOCATION header is only supported on #{LOCATION_HEADER_CATEGORIES.join('/')} templates, not #{category}")
+      end
+
+      # A limited-time offer reshapes the rest of the template: no footer, a shorter
+      # body, a media-only header, and a copy-code button that must come first.
+      # @return [void]
+      def validate_limited_time_offer
+        return unless api_types.include?(Component::LimitedTimeOffer::Defaults::TYPE)
+
+        validate_offer_has_no_footer
+        validate_offer_body_length
+        validate_offer_header_format
+        validate_offer_buttons
+      end
+
+      # @return [void]
+      def validate_offer_has_no_footer
+        return unless api_types.include?(Component::Footer::Defaults::TYPE)
+
+        errors.add(:components, "a FOOTER is not allowed in a LIMITED_TIME_OFFER template")
+      end
+
+      # @return [void]
+      def validate_offer_body_length
+        text = find(Component::Body::Defaults::TYPE)&.text
+        return if text.nil? || text.length <= Defaults::LIMITED_TIME_OFFER_MAX_BODY_LENGTH
+
+        errors.add(:components,
+          "the BODY of a LIMITED_TIME_OFFER template is limited to " \
+            "#{Defaults::LIMITED_TIME_OFFER_MAX_BODY_LENGTH} characters")
+      end
+
+      # @return [void]
+      def validate_offer_header_format
+        header = find(Component::Header::Defaults::TYPE)
+        return if header.nil? || LIMITED_TIME_OFFER_HEADER_FORMATS.include?(header.format)
+
+        errors.add(:components,
+          "the header must be IMAGE or VIDEO in a LIMITED_TIME_OFFER template, got #{header.format}")
+      end
+
+      # @return [void]
+      def validate_offer_buttons
+        buttons = find(Component::Buttons::Defaults::TYPE)&.buttons
+        return if buttons.nil?
+
+        copy_code = buttons.find { |button| button.is_a?(Button::CopyCode) }
+        return if copy_code.nil?
+
+        validate_offer_copy_code_position(buttons, copy_code)
+        validate_offer_copy_code_length(copy_code)
+      end
+
+      # @return [void]
+      def validate_offer_copy_code_position(buttons, copy_code)
+        return if buttons.index(copy_code).zero?
+
+        errors.add(:components, "the copy-code button must be first in a LIMITED_TIME_OFFER template")
+      end
+
+      # @return [void]
+      def validate_offer_copy_code_length(copy_code)
+        maximum = Defaults::LIMITED_TIME_OFFER_MAX_COPY_CODE_LENGTH
+        return if copy_code.example.to_s.length <= maximum
+
+        errors.add(:components,
+          "the copy-code example is limited to #{maximum} characters in a LIMITED_TIME_OFFER template")
+      end
+    end
+  end
+end