ruby-whatsapp 0.3.0

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

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    # Builds the `example` payload Meta requires alongside any component text that
+    # contains placeholders.
+    #
+    # This exists because the *key name* of that payload changes with both the
+    # component and the template's parameter format — four combinations that are easy
+    # to get wrong and are a common source of template rejections:
+    #
+    #            | POSITIONAL                    | NAMED
+    #   ---------+-------------------------------+--------------------------------
+    #   header   | header_text: ["Sale"]         | header_text_named_params: [...]
+    #   body     | body_text: [["a", "b"]]       | body_text_named_params: [...]
+    #
+    # Note the asymmetry: `header_text` is a flat array while `body_text` is an array
+    # *of arrays*. Meta documents no reason for it; it just is.
+    #
+    # Callers may pass a plain Array (positional), a Hash of name => example (named),
+    # Meta's own `[{param_name:, example:}]` array, or a fully-built payload hash
+    # copied verbatim out of Meta's docs — all four are accepted so pasting a known-
+    # good example from the API reference works without translation.
+    # Source: https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components/
+    module Example
+      # Maps a component role to its example key for each parameter format.
+      ROLES = {
+        header: { positional: :header_text, named: :header_text_named_params },
+        body: { positional: :body_text, named: :body_text_named_params },
+      }.freeze
+
+      # Keys that mean "the caller already built this payload, pass it through".
+      # `header_handle` is included because media headers carry an asset handle here
+      # rather than text parameters.
+      BUILT_KEYS = (ROLES.values.flat_map(&:values) + [:header_handle]).freeze
+
+      # Roles whose positional example is nested one level deeper.
+      NESTED_ROLES = [:body].freeze
+
+      class << self
+        # @param role [Symbol] `:header` or `:body`.
+        # @param parameter_format [String, Symbol, nil] see {ParameterFormats}.
+        # @param values [Array, Hash, String, nil] the example value(s).
+        # @return [Hash, nil] The example payload, or nil when there are no values.
+        # @raise [ArgumentError] if the role is unknown or the values do not match the
+        #   parameter format.
+        def serialize(role:, parameter_format:, values:)
+          keys = keys_for(role)
+          return if blank_value?(values)
+          return symbolize(values) if built?(values)
+
+          if ParameterFormats.named?(parameter_format)
+            { keys[:named] => named_params(values) }
+          else
+            { keys[:positional] => positional_values(role, values) }
+          end
+        end
+
+        # The number of example values supplied, whatever shape they arrived in.
+        #
+        # Used by components to check the example count against the placeholder count
+        # without needing to know which of the four shapes the caller used.
+        # @return [Integer]
+        def count(role:, parameter_format:, values:)
+          payload = serialize(role:, parameter_format:, values:)
+          return 0 if payload.nil?
+
+          key, value = payload.first
+          return value.size if key.to_s.end_with?("named_params")
+          return Array(value.first).size if NESTED_ROLES.any? { |r| ROLES[r][:positional] == key }
+
+          value.size
+        end
+
+      private
+
+        # @raise [ArgumentError] if the role has no example key mapping.
+        def keys_for(role)
+          ROLES.fetch(role.to_sym) do
+            raise ArgumentError, "Unknown example role: #{role.inspect}. Known roles: #{ROLES.keys.join(', ')}"
+          end
+        end
+
+        # @return [Boolean] true when there is nothing to serialize.
+        def blank_value?(values)
+          values.nil? || (values.respond_to?(:empty?) && values.empty?)
+        end
+
+        # Whether the hash is already a built example payload rather than raw values.
+        #
+        # Decided by key name against the closed {BUILT_KEYS} set. A named parameter
+        # that happens to be called e.g. `body_text` would be misread as a built
+        # payload; that is an accepted trade for being able to paste Meta's examples.
+        # @return [Boolean]
+        def built?(values)
+          return false unless values.is_a?(Hash)
+
+          values.keys.map(&:to_sym).all? { |key| BUILT_KEYS.include?(key) }
+        end
+
+        # @return [Hash]
+        def symbolize(values)
+          values.transform_keys(&:to_sym)
+        end
+
+        # @return [Array<Hash>] Meta's `[{param_name:, example:}]` shape.
+        # @raise [ArgumentError] if the values are not a usable named shape.
+        def named_params(values)
+          case values
+          when Hash then values.map { |name, example| { param_name: name.to_s, example: } }
+          when Array then values.map { |entry| named_param_entry(entry) }
+          else raise ArgumentError, named_params_error(values)
+          end
+        end
+
+        # @return [Hash]
+        # @raise [ArgumentError] if the entry is not a param_name/example pair.
+        def named_param_entry(entry)
+          raise ArgumentError, named_params_error(entry) unless entry.is_a?(Hash)
+
+          normalized = symbolize(entry)
+          raise ArgumentError, named_params_error(entry) unless normalized.key?(:param_name)
+
+          { param_name: normalized[:param_name].to_s, example: normalized[:example] }
+        end
+
+        # @return [String]
+        def named_params_error(values)
+          "Expected named parameter examples as a Hash of name => example, or an " \
+            "array of { param_name:, example: } hashes, got: #{values.inspect}"
+        end
+
+        # @return [Array] The positional values, nested for roles that require it.
+        # @raise [ArgumentError] if a Hash is given for a positional format.
+        def positional_values(role, values)
+          if values.is_a?(Hash)
+            raise ArgumentError,
+              "Expected positional parameter examples as an Array, got a Hash: #{values.inspect}. " \
+                "Did you mean to set parameter_format to #{ParameterFormats::NAMED}?"
+          end
+
+          list = values.is_a?(Array) ? values : [values]
+          NESTED_ROLES.include?(role.to_sym) ? [list] : list
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/library_template/body_inputs.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class LibraryTemplate
+      # The optional body content a library template exposes for customisation.
+      #
+      # Library templates have fixed wording, so these are toggles rather than text:
+      # each one asks Meta to include a pre-written line or link in the body.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/template-library
+      class BodyInputs
+        include ValueObject
+
+        module Defaults
+          CODE_EXPIRATION_RANGE = (1..90)
+        end
+
+        # @!attribute [rw] add_contact_number
+        #   @return [Boolean, nil]
+        attr_accessor :add_contact_number
+
+        # @!attribute [rw] add_learn_more_link
+        #   @return [Boolean, nil]
+        attr_accessor :add_learn_more_link
+
+        # @!attribute [rw] add_security_recommendation
+        #   @return [Boolean, nil]
+        attr_accessor :add_security_recommendation
+
+        # @!attribute [rw] add_track_package_link
+        #   @return [Boolean, nil]
+        attr_accessor :add_track_package_link
+
+        # @!attribute [rw] code_expiration_minutes
+        #   @return [Integer, nil]
+        attr_accessor :code_expiration_minutes
+
+        validate :validate_code_expiration
+
+        # @param add_contact_number [Boolean, nil]
+        # @param add_learn_more_link [Boolean, nil]
+        # @param add_security_recommendation [Boolean, nil]
+        # @param add_track_package_link [Boolean, nil]
+        # @param code_expiration_minutes [Integer, nil] Must be within 1..90.
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(add_contact_number: nil, add_learn_more_link: nil, add_security_recommendation: nil,
+          add_track_package_link: nil, code_expiration_minutes: nil)
+          @add_contact_number = add_contact_number
+          @add_learn_more_link = add_learn_more_link
+          @add_security_recommendation = add_security_recommendation
+          @add_track_package_link = add_track_package_link
+          @code_expiration_minutes = code_expiration_minutes
+
+          validate!
+        end
+
+        # @return [Hash] Only the toggles that were explicitly set.
+        def serialize
+          {
+            add_contact_number:,
+            add_learn_more_link:,
+            add_security_recommendation:,
+            add_track_package_link:,
+            code_expiration_minutes:,
+          }.compact
+        end
+
+      private
+
+        # @return [void]
+        def validate_code_expiration
+          return if code_expiration_minutes.nil?
+          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/library_template/button_inputs.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class LibraryTemplate
+      # One button's customisable values when cloning a library template.
+      #
+      # Deliberately *not* the same as {Button}: a library template already declares
+      # which buttons it has and what they say, so these inputs only fill in the parts
+      # Meta cannot know — a destination URL, a phone number, an app signature. There is
+      # no `text`, and the shapes differ from the create-a-button-from-scratch ones (a
+      # URL arrives as a `{base_url:, url_suffix_example:}` pair rather than a single
+      # string with a placeholder).
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/template-library
+      class ButtonInputs
+        include ValueObject
+
+        # The button kinds a library template may expose for customisation. Wider than
+        # {Button::TYPES} because Meta documents these by name here even where it
+        # publishes no create-from-scratch schema for them.
+        module Types
+          QUICK_REPLY = "QUICK_REPLY"
+          URL = "URL"
+          PHONE_NUMBER = "PHONE_NUMBER"
+          OTP = "OTP"
+          MPM = "MPM"
+          CATALOG = "CATALOG"
+          FLOW = "FLOW"
+          VOICE_CALL = "VOICE_CALL"
+          APP = "APP"
+
+          ALL = [QUICK_REPLY, URL, PHONE_NUMBER, OTP, MPM, CATALOG, FLOW, VOICE_CALL, APP].freeze
+        end
+
+        # @!attribute [rw] type
+        #   @return [String] one of {Types::ALL}.
+        attr_accessor :type
+
+        # @!attribute [rw] url
+        #   @return [Hash, nil] `{ base_url:, url_suffix_example: }`.
+        attr_accessor :url
+
+        # @!attribute [rw] phone_number
+        #   @return [String, nil]
+        attr_accessor :phone_number
+
+        # @!attribute [rw] otp_type
+        #   @return [String, nil]
+        attr_accessor :otp_type
+
+        # @!attribute [rw] zero_tap_terms_accepted
+        #   @return [Boolean, nil]
+        attr_accessor :zero_tap_terms_accepted
+
+        # @!attribute [rw] supported_apps
+        #   @return [Array<Button::Otp::SupportedApp>, nil]
+        attr_accessor :supported_apps
+
+        validates :type, presence: true, inclusion: { in: Types::ALL }
+        validate :validate_url
+        validate :validate_phone_number
+        validate :validate_supported_apps
+
+        # @param type [String, Symbol] One of {Types::ALL}, any casing.
+        # @param url [Hash, nil] Required for URL: `{ base_url:, url_suffix_example: }`.
+        # @param phone_number [String, nil] Required for PHONE_NUMBER.
+        # @param otp_type [String, Symbol, nil] For OTP inputs.
+        # @param zero_tap_terms_accepted [Boolean, nil] For zero-tap OTP inputs.
+        # @param supported_apps [Array<Hash, Button::Otp::SupportedApp>, nil] Required
+        #   for APP.
+        #  @raise [ActiveModel::ValidationError] if validation fails.
+        def initialize(type:, url: nil, phone_number: nil, otp_type: nil,
+          zero_tap_terms_accepted: nil, supported_apps: nil)
+          @type = normalize_type(type)
+          @url = url&.then { |value| symbolize(value) }
+          @phone_number = phone_number
+          @otp_type = otp_type&.to_s&.upcase
+          @zero_tap_terms_accepted = zero_tap_terms_accepted
+          @supported_apps = build_supported_apps(supported_apps)
+
+          validate!
+        end
+
+        # @return [Hash] The serialized button input.
+        def serialize
+          {
+            type:,
+            url:,
+            phone_number:,
+            otp_type:,
+            zero_tap_terms_accepted:,
+            supported_apps: supported_apps&.map(&:serialize),
+          }.compact
+        end
+
+      private
+
+        # @return [String, nil]
+        def normalize_type(value)
+          return if value.nil?
+
+          candidate = value.to_s.upcase
+          Types::ALL.include?(candidate) ? candidate : value.to_s
+        end
+
+        # @return [Hash]
+        def symbolize(hash)
+          hash.transform_keys(&:to_sym)
+        end
+
+        # @return [Array<Button::Otp::SupportedApp>, nil]
+        def build_supported_apps(apps)
+          return if apps.nil?
+
+          Array(apps).map do |app|
+            app.is_a?(Button::Otp::SupportedApp) ? app : Button::Otp::SupportedApp.new(**app)
+          end
+        end
+
+        # @return [void]
+        def validate_url
+          return unless type == Types::URL
+          return unless blank_value?(url) || blank_value?(url[:base_url])
+
+          errors.add(:url, "requires a base_url for a #{Types::URL} button input")
+        end
+
+        # @return [void]
+        def validate_phone_number
+          return unless type == Types::PHONE_NUMBER
+          return unless blank_value?(phone_number)
+
+          errors.add(:phone_number, "can't be blank for a #{Types::PHONE_NUMBER} button input")
+        end
+
+        # @return [void]
+        def validate_supported_apps
+          return unless type == Types::APP
+          return unless blank_value?(supported_apps)
+
+          errors.add(:supported_apps, "can't be blank for an #{Types::APP} button input")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    # The payload for cloning one of Meta's pre-written library templates.
+    #
+    # A separate class from {Template} rather than another mode on it, because this
+    # payload carries **no components at all** — the library template already defines
+    # them, and only the parts Meta cannot know (a URL, a phone number, whether to
+    # append an optional line) are supplied as inputs. Folding that into {Template}
+    # would mean defeating its central "exactly one BODY" invariant.
+    #
+    # The payoff is instant approval: library templates are already categorised and
+    # reviewed, so the create response usually comes back APPROVED rather than PENDING.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/template-library
+    class LibraryTemplate
+      include ValueObject
+
+      # @!attribute [rw] name
+      #   @return [String] The name to give *your* copy of the template.
+      attr_accessor :name
+
+      # @!attribute [rw] language
+      #   @return [String]
+      attr_accessor :language
+
+      # @!attribute [rw] category
+      #   @return [String]
+      attr_accessor :category
+
+      # @!attribute [rw] library_template_name
+      #   @return [String] The library template being cloned.
+      attr_accessor :library_template_name
+
+      # @!attribute [rw] library_template_body_inputs
+      #   @return [LibraryTemplate::BodyInputs, nil]
+      attr_accessor :library_template_body_inputs
+
+      # @!attribute [rw] library_template_button_inputs
+      #   @return [Array<LibraryTemplate::ButtonInputs>, nil]
+      attr_accessor :library_template_button_inputs
+
+      validates :name, presence: true,
+        format: { with: Template::Defaults::NAME_PATTERN,
+                  message: "must contain only lowercase alphanumeric characters and underscores", },
+        length: { maximum: Template::Defaults::MAX_NAME_LENGTH }
+      validates :language, presence: true
+      validates :category, presence: true, inclusion: { in: Categories::ALL }
+      validates :library_template_name, presence: true
+      validate :validate_language_code
+
+      # @param name [String] The name for your copy; same rules as {Template}.
+      # @param language [String] A locale code.
+      # @param category [String, Symbol] One of {Categories::ALL}.
+      # @param library_template_name [String] The library template to clone.
+      # @param library_template_body_inputs [Hash, BodyInputs, nil] Optional body toggles.
+      # @param library_template_button_inputs [Array<Hash, ButtonInputs>, nil] Optional
+      #   per-button values.
+      #  @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(name:, language:, category:, library_template_name:,
+        library_template_body_inputs: nil, library_template_button_inputs: nil)
+        @name = name
+        @language = language
+        @category = Categories.normalize(category)
+        @library_template_name = library_template_name
+        @library_template_body_inputs = build_body_inputs(library_template_body_inputs)
+        @library_template_button_inputs = build_button_inputs(library_template_button_inputs)
+
+        validate!
+      end
+
+      # @return [Hash] The create-from-library payload.
+      #
+      # Note: Meta's docs show `library_template_button_inputs` as a JSON-*stringified*
+      # array while the Graph API reference types it `array<JSON object>`. A real array
+      # is emitted here, which matches the reference and how every other field on this
+      # edge behaves. If the API rejects it, this method is the single place to change.
+      def serialize
+        {
+          name:,
+          language:,
+          category:,
+          library_template_name:,
+          library_template_body_inputs: library_template_body_inputs&.serialize,
+          library_template_button_inputs: library_template_button_inputs&.map(&:serialize),
+        }.compact
+      end
+
+    private
+
+      # @return [BodyInputs, nil]
+      def build_body_inputs(inputs)
+        return if blank_value?(inputs)
+        return inputs if inputs.is_a?(BodyInputs)
+
+        BodyInputs.new(**inputs)
+      end
+
+      # @return [Array<ButtonInputs>, nil]
+      def build_button_inputs(inputs)
+        return if blank_value?(inputs)
+
+        Array(inputs).map { |input| input.is_a?(ButtonInputs) ? input : ButtonInputs.new(**input) }
+      end
+
+      # @return [void]
+      def validate_language_code
+        return if blank_value?(language) || Utils::LanguageCodes.valid?(language)
+
+        errors.add(:language, "#{language.inspect} is not a valid WhatsApp language code")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    # The two placeholder styles a template can declare, set once per template via
+    # `parameter_format` and inherited by every component in it.
+    #
+    # POSITIONAL uses `{{1}}`, `{{2}}` — index numbers starting at 1, and send-side
+    # values must be supplied in the same order. NAMED uses `{{first_name}}` —
+    # lowercase-and-underscore names, and send-side values may be supplied in any
+    # order. POSITIONAL is Meta's default when the field is omitted.
+    #
+    # The format also decides the *key name* of a component's `example` payload,
+    # which is why it has to be threaded down into each component. See {Example}.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/overview
+    module ParameterFormats
+      POSITIONAL = "POSITIONAL"
+      NAMED = "NAMED"
+
+      ALL = [POSITIONAL, NAMED].freeze
+
+      # Normalizes caller input to a canonical uppercase format string.
+      #
+      # Meta's own docs are inconsistent about enum casing, so callers may
+      # reasonably pass `:named`, `"named"`, or `"NAMED"`. 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.named?(value)
+        normalize(value) == NAMED
+      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/placeholders.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    # Parses the `{{...}}` placeholders out of template text.
+    #
+    # Three components need this (header text, body text, and the single variable a
+    # URL button may append), so the pattern and the "what style is this?" question
+    # live in one place rather than being re-derived per component.
+    #
+    # Placeholder names are collapsed to unique values in order of first appearance:
+    # Meta counts a repeated `{{1}}` or `{{name}}` as one parameter, so the count a
+    # caller must supply examples for is the unique count — that is {.count}. Where a
+    # rule is about *position* rather than parameters, {.occurrences} counts repeats
+    # instead; see the URL button.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/overview
+    module Placeholders
+      # Matches `{{name}}` / `{{1}}`, tolerating internal whitespace. Deliberately
+      # restricted to word characters so malformed forms (`{{}}`, `{{a-b}}`) are not
+      # mistaken for parameters.
+      PATTERN = /\{\{\s*(\w+)\s*\}\}/
+
+      # @param text [String, nil]
+      # @return [Array<String>] Unique placeholder names, in order of appearance.
+      def self.extract(text)
+        text.to_s.scan(PATTERN).flatten.uniq
+      end
+
+      # @param text [String, nil]
+      # @return [Integer] The number of unique placeholders.
+      def self.count(text)
+        extract(text).size
+      end
+
+      # @param text [String, nil]
+      # @return [Integer] The number of placeholder occurrences, counting repeats.
+      #   Contrast {.count}, which collapses repeated names. The URL button rule is
+      #   positional — a single variable, appended at the very end — so a second
+      #   occurrence breaks it even when it names the same parameter.
+      def self.occurrences(text)
+        text.to_s.scan(PATTERN).size
+      end
+
+      # @param text [String, nil]
+      # @return [Symbol, nil] `:positional`, `:named`, `:mixed`, or nil when the text
+      #   has no placeholders.
+      def self.style(text)
+        names = extract(text)
+        return if names.empty?
+
+        numeric, rest = names.partition { |name| name.match?(/\A\d+\z/) }
+
+        return :positional if rest.empty?
+        return :named if numeric.empty?
+
+        :mixed
+      end
+
+      # @param text [String, nil]
+      # @return [Boolean] true when the text has placeholders and all are numeric.
+      def self.positional?(text)
+        style(text) == :positional
+      end
+
+      # @param text [String, nil]
+      # @return [Boolean] true when the text has placeholders and none are numeric.
+      def self.named?(text)
+        style(text) == :named
+      end
+
+      # Whether positional placeholders form the run 1..n that Meta requires.
+      #
+      # Order of appearance in the text does not matter — `"{{2}} after {{1}}"` is
+      # valid — only that the set of indexes has no gaps and starts at 1. Text with
+      # no placeholders, or named placeholders, is trivially sequential.
+      # @param text [String, nil]
+      # @return [Boolean]
+      def self.sequential?(text)
+        indexes = extract(text).grep(/\A\d+\z/).map(&:to_i)
+        return true if indexes.empty?
+
+        indexes.sort == (1..indexes.size).to_a
+      end
+    end
+  end
+end