ruby-whatsapp 0.3.0

data/lib/ruby/whatsapp/message_templates/response/collection.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    module Response
+      # A page of templates: `{data, paging, summary}`.
+      #
+      # Enumerable over its templates, so `list.select(&:approved?)` reads naturally
+      # without reaching for `.data` first.
+      #
+      # Paging is exposed rather than followed automatically: the caller decides whether
+      # to walk the whole account, and passing {#next_cursor} back as `after:` is one
+      # line. Auto-pagination would hide an unbounded number of requests behind a single
+      # innocuous-looking call.
+      # Source: https://developers.facebook.com/docs/graph-api/reference/whats-app-business-account/message_templates/
+      class Collection
+        include Enumerable
+
+        # @!attribute [rw] data
+        #   @return [Array<Node>]
+        attr_accessor :data
+
+        # @!attribute [rw] paging
+        #   @return [Paging, nil]
+        attr_accessor :paging
+
+        # @!attribute [rw] summary
+        #   @return [Summary, nil]
+        attr_accessor :summary
+
+        # @param data [Array<Node>]
+        # @param paging [Paging, nil]
+        # @param summary [Summary, nil]
+        def initialize(data: [], paging: nil, summary: nil)
+          @data = data
+          @paging = paging
+          @summary = summary
+        end
+
+        class << self
+          # @param response [Hash, nil] The parsed response body.
+          # @return [Collection]
+          def deserialize(response)
+            response ||= {}
+
+            new(
+              data: Array(response["data"]).map { |node| Node.deserialize(node) },
+              paging: response["paging"] && Paging.deserialize(response["paging"]),
+              summary: response["summary"] && Summary.deserialize(response["summary"])
+            )
+          end
+        end
+
+        # @yieldparam template [Node]
+        # @return [Enumerator]
+        def each(&)
+          data.each(&)
+        end
+
+        # The cursor to pass as `after:` to fetch the next page.
+        # @return [String, nil]
+        def next_cursor
+          paging&.after
+        end
+
+        # How many more templates the account can hold.
+        # @return [Integer, nil]
+        def remaining
+          summary&.remaining
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/response/created.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    module Response
+      # The response to creating a template: `{id, status, category}`.
+      #
+      # `status` is worth checking rather than assuming: a template built from scratch
+      # normally comes back PENDING and takes up to 24 hours to review, but a library
+      # clone or an authentication template is usually APPROVED immediately, and a
+      # category Meta disagrees with comes back REJECTED right away.
+      #
+      # `category` is echoed back because Meta may have reassigned it — automatic
+      # recategorisation has been the default since 2025-04-09.
+      # Source: https://developers.facebook.com/docs/graph-api/reference/whats-app-business-account/message_templates/
+      class Created
+        # @!attribute [rw] id
+        #   @return [String, nil]
+        attr_accessor :id
+
+        # @!attribute [rw] status
+        #   @return [String, nil]
+        attr_accessor :status
+
+        # @!attribute [rw] category
+        #   @return [String, nil] The category Meta actually assigned.
+        attr_accessor :category
+
+        # @param id [String, nil]
+        # @param status [String, nil]
+        # @param category [String, nil]
+        def initialize(id: nil, status: nil, category: nil)
+          @id = id
+          @status = status
+          @category = category
+        end
+
+        class << self
+          # @param data [Hash, nil] The parsed response body.
+          # @return [Created]
+          def deserialize(data)
+            data ||= {}
+
+            new(id: data["id"], status: data["status"], category: data["category"])
+          end
+        end
+
+        # @return [Boolean] Whether the template is already sendable.
+        def approved?
+          status == Statuses::APPROVED
+        end
+
+        # @return [Boolean] Whether the template is still in review.
+        def pending?
+          status == Statuses::PENDING
+        end
+
+        # @return [Boolean] Whether the template failed review.
+        def rejected?
+          status == Statuses::REJECTED
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/response/node.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    module Response
+      # A full template as Meta returns it, from reading one template or from each
+      # element of a list.
+      #
+      # `components` is deliberately left as raw hashes rather than rebuilt into the
+      # {Component} classes. Those classes validate a payload being *written*, whereas
+      # this is Meta's own echo of it: it carries fields the write side does not model,
+      # and running write-side rules over data we did not author would raise on
+      # perfectly valid responses. Read it as data; build a new {Template} when you want
+      # to change something.
+      # Source: https://developers.facebook.com/docs/graph-api/reference/whats-app-business-hsm/
+      class Node
+        # @!attribute [rw] id
+        #   @return [String, nil]
+        attr_accessor :id
+
+        # @!attribute [rw] name
+        #   @return [String, nil]
+        attr_accessor :name
+
+        # @!attribute [rw] status
+        #   @return [String, nil] One of {Statuses::ALL}.
+        attr_accessor :status
+
+        # @!attribute [rw] category
+        #   @return [String, nil]
+        attr_accessor :category
+
+        # @!attribute [rw] language
+        #   @return [String, nil]
+        attr_accessor :language
+
+        # @!attribute [rw] components
+        #   @return [Array<Hash>] Raw component hashes — see the class comment.
+        attr_accessor :components
+
+        # @!attribute [rw] parameter_format
+        #   @return [String, nil]
+        attr_accessor :parameter_format
+
+        # @!attribute [rw] sub_category
+        #   @return [String, nil]
+        attr_accessor :sub_category
+
+        # @!attribute [rw] rejected_reason
+        #   @return [String, nil] One of {Statuses::RejectedReasons::ALL}.
+        attr_accessor :rejected_reason
+
+        # @!attribute [rw] quality_score
+        #   @return [QualityScore, nil]
+        attr_accessor :quality_score
+
+        # @!attribute [rw] previous_category
+        #   @return [String, nil] Set after an automatic recategorisation.
+        attr_accessor :previous_category
+
+        # @!attribute [rw] correct_category
+        #   @return [String, nil] The category Meta believes this should be.
+        attr_accessor :correct_category
+
+        # @!attribute [rw] message_send_ttl_seconds
+        #   @return [Integer, nil]
+        attr_accessor :message_send_ttl_seconds
+
+        # @!attribute [rw] cta_url_link_tracking_opted_out
+        #   @return [Boolean, nil]
+        attr_accessor :cta_url_link_tracking_opted_out
+
+        # @!attribute [rw] library_template_name
+        #   @return [String, nil] Set when the template was cloned from the library.
+        attr_accessor :library_template_name
+
+        # @param kwargs [Hash] One key per documented node field.
+        def initialize(id: nil, name: nil, status: nil, category: nil, language: nil, components: [],
+          parameter_format: nil, sub_category: nil, rejected_reason: nil, quality_score: nil,
+          previous_category: nil, correct_category: nil, message_send_ttl_seconds: nil,
+          cta_url_link_tracking_opted_out: nil, library_template_name: nil)
+          @id = id
+          @name = name
+          @status = status
+          @category = category
+          @language = language
+          @components = components
+          @parameter_format = parameter_format
+          @sub_category = sub_category
+          @rejected_reason = rejected_reason
+          @quality_score = quality_score
+          @previous_category = previous_category
+          @correct_category = correct_category
+          @message_send_ttl_seconds = message_send_ttl_seconds
+          @cta_url_link_tracking_opted_out = cta_url_link_tracking_opted_out
+          @library_template_name = library_template_name
+        end
+
+        class << self
+          # @param data [Hash, nil] The parsed response body, or one element of a list.
+          # @return [Node]
+          def deserialize(data)
+            data ||= {}
+
+            new(
+              id: data["id"],
+              name: data["name"],
+              status: data["status"],
+              category: data["category"],
+              language: data["language"],
+              components: Array(data["components"]),
+              parameter_format: data["parameter_format"],
+              sub_category: data["sub_category"],
+              rejected_reason: data["rejected_reason"],
+              quality_score: data["quality_score"] && QualityScore.deserialize(data["quality_score"]),
+              previous_category: data["previous_category"],
+              correct_category: data["correct_category"],
+              message_send_ttl_seconds: data["message_send_ttl_seconds"],
+              cta_url_link_tracking_opted_out: data["cta_url_link_tracking_opted_out"],
+              library_template_name: data["library_template_name"]
+            )
+          end
+        end
+
+        # @return [Boolean] Whether the template can currently be sent.
+        def approved?
+          status == Statuses::APPROVED
+        end
+
+        # @return [Boolean]
+        def rejected?
+          status == Statuses::REJECTED
+        end
+
+        # @return [Boolean]
+        def paused?
+          status == Statuses::PAUSED
+        end
+
+        # Whether {MessageTemplates#update} would be accepted for this template.
+        #
+        # Status is the only part that can be checked locally. Approved templates are
+        # also rate limited to 10 edits per 30 days and 1 per 24 hours, which only the
+        # API can adjudicate.
+        # @return [Boolean]
+        def editable?
+          Statuses::EDITABLE.include?(status)
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/response/paging.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    module Response
+      # Graph API cursor pagination for a template list.
+      #
+      # Flattens the nested `paging.cursors` object, since the intermediate level
+      # carries no information of its own.
+      # Source: https://developers.facebook.com/docs/graph-api/reference/whats-app-business-account/message_templates/
+      class Paging
+        # @!attribute [rw] before
+        #   @return [String, nil] Cursor for the previous page.
+        attr_accessor :before
+
+        # @!attribute [rw] after
+        #   @return [String, nil] Cursor for the next page.
+        attr_accessor :after
+
+        # @param before [String, nil]
+        # @param after [String, nil]
+        def initialize(before: nil, after: nil)
+          @before = before
+          @after = after
+        end
+
+        class << self
+          # @param data [Hash, nil] The raw `paging` object.
+          # @return [Paging]
+          def deserialize(data)
+            cursors = (data || {})["cursors"] || {}
+
+            new(before: cursors["before"], after: cursors["after"])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/response/quality_score.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    module Response
+      # A template's quality assessment, derived from usage, recipient feedback and
+      # engagement. A falling score is what precedes a PAUSED and then DISABLED status.
+      #
+      # Best-effort schema: Meta names the shape (`WhatsAppBusinessHSMQualityScoreShape`)
+      # in the Graph API reference but does not publish its sub-fields. The three mapped
+      # here are what live responses have been observed to carry. Validate against a real
+      # response before relying on them, as with the best-effort webhook classes in
+      # `lib/ruby/whatsapp/webhook/CLAUDE.md`.
+      # Source: https://developers.facebook.com/docs/graph-api/reference/whats-app-business-hsm/
+      class QualityScore
+        # @!attribute [rw] score
+        #   @return [String, nil] One of {Statuses::QualityScores::ALL}.
+        attr_accessor :score
+
+        # @!attribute [rw] date
+        #   @return [Integer, String, nil] When the score was last assessed.
+        attr_accessor :date
+
+        # @!attribute [rw] reasons
+        #   @return [Array]
+        attr_accessor :reasons
+
+        # @param score [String, nil]
+        # @param date [Integer, String, nil]
+        # @param reasons [Array, nil]
+        def initialize(score: nil, date: nil, reasons: [])
+          @score = score
+          @date = date
+          @reasons = reasons
+        end
+
+        class << self
+          # @param data [Hash, nil]
+          # @return [QualityScore]
+          def deserialize(data)
+            data ||= {}
+
+            new(score: data["score"], date: data["date"], reasons: Array(data["reasons"]))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/response/summary.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    module Response
+      # The `summary` block of a template list.
+      #
+      # Worth reading rather than ignoring: `message_template_count` against
+      # `message_template_limit` is the only way to see how close a WABA is to its
+      # template cap — 250 for an unverified business portfolio, up to 6,000 for a
+      # verified one with an approved display name. Hitting it turns every subsequent
+      # create into an error.
+      # Source: https://developers.facebook.com/docs/graph-api/reference/whats-app-business-account/message_templates/
+      class Summary
+        # @!attribute [rw] total_count
+        #   @return [Integer, nil]
+        attr_accessor :total_count
+
+        # @!attribute [rw] message_template_count
+        #   @return [Integer, nil] Templates currently on the account.
+        attr_accessor :message_template_count
+
+        # @!attribute [rw] message_template_limit
+        #   @return [Integer, nil] The account's cap.
+        attr_accessor :message_template_limit
+
+        # @!attribute [rw] are_translations_complete
+        #   @return [Boolean, nil]
+        attr_accessor :are_translations_complete
+
+        # @param total_count [Integer, nil]
+        # @param message_template_count [Integer, nil]
+        # @param message_template_limit [Integer, nil]
+        # @param are_translations_complete [Boolean, nil]
+        def initialize(total_count: nil, message_template_count: nil, message_template_limit: nil,
+          are_translations_complete: nil)
+          @total_count = total_count
+          @message_template_count = message_template_count
+          @message_template_limit = message_template_limit
+          @are_translations_complete = are_translations_complete
+        end
+
+        class << self
+          # @param data [Hash, nil] The raw `summary` object.
+          # @return [Summary]
+          def deserialize(data)
+            data ||= {}
+
+            new(
+              total_count: data["total_count"],
+              message_template_count: data["message_template_count"],
+              message_template_limit: data["message_template_limit"],
+              are_translations_complete: data["are_translations_complete"]
+            )
+          end
+        end
+
+        # How many more templates the account can hold.
+        # @return [Integer, nil] nil when either figure is missing.
+        def remaining
+          return if message_template_limit.nil? || message_template_count.nil?
+
+          message_template_limit - message_template_count
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    # Deserializers for the responses of the template-management edge.
+    #
+    # Unlike {Whatsapp::Messages::Response}, which parses one shape, this edge answers
+    # in four different ones depending on the operation — hence a namespace of small
+    # classes rather than a single one with optional fields:
+    #
+    #   {Created}    `{id, status, category}`        create, create_from_library, upsert
+    #   {Node}       the full template object        find, and each element of a list
+    #   {Collection} `{data, paging, summary}`       list
+    #   —            `{success: true}`               update and delete, returned as a
+    #                                                plain boolean, as {Media#delete} does
+    #
+    # Every class follows the gem's `.deserialize(data)` convention and tolerates a nil
+    # or partial payload, so a field Meta stops sending cannot raise.
+    module Response
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    # The review and health states a template moves through.
+    #
+    # Only APPROVED templates can be sent. Status changes arrive asynchronously via the
+    # `message_template_status_update` webhook, already modelled by
+    # {Whatsapp::Webhook::MessageTemplateStatusUpdate} — polling {MessageTemplates#find}
+    # is the fallback, not the intended path.
+    # Source: https://developers.facebook.com/docs/graph-api/reference/whats-app-business-hsm/
+    module Statuses
+      # Passed review and sendable.
+      APPROVED = "APPROVED"
+      # In review; can take up to 24 hours.
+      PENDING = "PENDING"
+      # Failed review or violated policy. See `rejected_reason`.
+      REJECTED = "REJECTED"
+      # Suspended after recurring negative feedback or low read rates.
+      PAUSED = "PAUSED"
+      # Permanently disabled. Cannot be sent, and cannot be deleted.
+      DISABLED = "DISABLED"
+      # An appeal is in progress.
+      IN_APPEAL = "IN_APPEAL"
+      # Deleted, with a 30-day window for messages already in flight.
+      PENDING_DELETION = "PENDING_DELETION"
+      DELETED = "DELETED"
+      # Over a limit.
+      LIMIT_EXCEEDED = "LIMIT_EXCEEDED"
+      # Inactive for 12 months or more.
+      ARCHIVED = "ARCHIVED"
+
+      ALL = [
+        APPROVED, PENDING, REJECTED, PAUSED, DISABLED,
+        IN_APPEAL, PENDING_DELETION, DELETED, LIMIT_EXCEEDED, ARCHIVED,
+      ].freeze
+
+      # The only statuses Meta allows a template to be edited in. Approved templates
+      # additionally carry rate limits (10 edits per 30 days, and 1 per 24 hours) that
+      # cannot be checked locally.
+      EDITABLE = [APPROVED, REJECTED, PAUSED].freeze
+
+      # Reasons Meta gives for a REJECTED status.
+      module RejectedReasons
+        NONE = "NONE"
+        ABUSIVE_CONTENT = "ABUSIVE_CONTENT"
+        INVALID_FORMAT = "INVALID_FORMAT"
+        PROMOTIONAL = "PROMOTIONAL"
+        TAG_CONTENT_MISMATCH = "TAG_CONTENT_MISMATCH"
+        SCAM = "SCAM"
+
+        ALL = [NONE, ABUSIVE_CONTENT, INVALID_FORMAT, PROMOTIONAL, TAG_CONTENT_MISMATCH, SCAM].freeze
+      end
+
+      # Quality buckets derived from recipient feedback and engagement.
+      module QualityScores
+        GREEN = "GREEN"
+        YELLOW = "YELLOW"
+        RED = "RED"
+        UNKNOWN = "UNKNOWN"
+
+        ALL = [GREEN, YELLOW, RED, UNKNOWN].freeze
+      end
+    end
+  end
+end