ruby-whatsapp 0.4.0 → 0.4.2

data/docs/webhooks/template_category_update.md

@@ -0,0 +1,52 @@
+# `template_category_update`
+
+Meta reclassified a template — most often moving something you filed as `UTILITY` into
+`MARKETING`. This matters because category determines **how you are billed** and
+whether the message is subject to marketing opt-outs.
+
+`Whatsapp::Webhook::TemplateCategoryUpdate` · confidence: **moderate-high**
+
+## Payload
+
+```json
+{ "field": "template_category_update",
+  "value": {
+    "message_template_id": "123",
+    "message_template_name": "order_confirmation",
+    "message_template_language": "en_US",
+    "previous_category": "MARKETING",
+    "new_category": "UTILITY",
+    "correct_category": "UTILITY"
+  } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `message_template_id` | The template's ID |
+| `message_template_name` | Its name |
+| `message_template_language` | Its locale |
+| `previous_category` | What it was |
+| `new_category` | What it is now |
+| `correct_category` | What Meta believes it should be |
+
+## Handling it
+
+```ruby
+when "template_category_update"
+  update = change.value
+
+  MessageTemplate
+    .find_by(meta_id: update.message_template_id)
+    &.update!(category: update.new_category)
+
+  Billing.recheck!(update.message_template_name) if update.new_category == "MARKETING"
+```
+
+> **Best-effort schema.** Meta publishes no JSON example for this field. Validate
+> against a real payload before depending on it in production.
+
+---
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview

data/docs/webhooks/user_preferences.md

@@ -0,0 +1,48 @@
+# `user_preferences`
+
+A customer changed their marketing preferences — most importantly, opting **out**.
+Respecting this is not optional: continuing to send marketing to someone who stopped
+you damages your quality rating and breaches Meta's policy.
+
+`Whatsapp::Webhook::UserPreferences` · confidence: **moderate**
+
+## Payload
+
+```json
+{ "field": "user_preferences",
+  "value": { "wa_id": "16505551234",
+             "detail": "stopped marketing messages",
+             "value": "stop",
+             "timestamp": "1750263773" } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `wa_id` | The customer's WhatsApp ID |
+| `detail` | Human-readable description |
+| `value` | `"stop"` or `"resume"` |
+| `timestamp` | Unix seconds, as a String |
+
+## Handling it
+
+```ruby
+when "user_preferences"
+  pref = change.value
+
+  Customer
+    .find_by(wa_id: pref.wa_id)
+    &.update!(marketing_opt_in: pref.value != "stop",
+              marketing_opt_in_changed_at: Time.at(pref.timestamp.to_i))
+```
+
+Gate every `MARKETING`-category [template send](../messages/template.md) on this flag.
+`UTILITY` and `AUTHENTICATION` templates are unaffected.
+
+> **Best-effort schema.** Meta publishes no JSON example for this field. Validate
+> against a real payload before depending on it in production.
+
+---
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview

data/lib/ruby/whatsapp/business_phone_number/account/details.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Account
+      # The WhatsApp Business Account node returned by {Get}.
+      #
+      # Only `id` and `name` are documented required; everything else arrives just when
+      # asked for via `fields`, so every attribute tolerates being absent. Status values
+      # are exposed as raw strings and are never validated on the way in — this is
+      # read-side data, and a value Meta adds later must still round-trip. The frozen
+      # constant modules below are for comparison, not enforcement, mirroring how
+      # {Whatsapp::MessageTemplates::Response::Node} keeps Meta's echoed payloads raw.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/whatsapp-business-account-api
+      class Details
+        # Meta's review status for the account.
+        module ReviewStatuses
+          APPROVED = "APPROVED"
+          DEFERRED = "DEFERRED"
+          PENDING = "PENDING"
+          REJECTED = "REJECTED"
+
+          ALL = [APPROVED, DEFERRED, PENDING, REJECTED].freeze
+        end
+
+        # Where the account sits in Meta's business verification process.
+        module VerificationStatuses
+          EXPIRED = "EXPIRED"
+          FAILED = "FAILED"
+          INELIGIBLE = "INELIGIBLE"
+          NOT_VERIFIED = "NOT_VERIFIED"
+          PENDING = "PENDING"
+          PENDING_NEED_MORE_INFO = "PENDING_NEED_MORE_INFO"
+          PENDING_SUBMISSION = "PENDING_SUBMISSION"
+          REJECTED = "REJECTED"
+          REVOKED = "REVOKED"
+          VERIFIED = "VERIFIED"
+
+          ALL = [EXPIRED, FAILED, INELIGIBLE, NOT_VERIFIED, PENDING, PENDING_NEED_MORE_INFO,
+                 PENDING_SUBMISSION, REJECTED, REVOKED, VERIFIED,].freeze
+        end
+
+        # Who owns the account: your own business, a client's, or a partner acting for one.
+        module OwnershipTypes
+          CLIENT_OWNED = "CLIENT_OWNED"
+          ON_BEHALF_OF = "ON_BEHALF_OF"
+          SELF = "SELF"
+
+          ALL = [CLIENT_OWNED, ON_BEHALF_OF, SELF].freeze
+        end
+
+        # @!attribute [rw] id
+        #   @return [String, nil] The account's unique identifier.
+        attr_accessor :id
+
+        # @!attribute [rw] name
+        #   @return [String, nil] The account's human-readable name.
+        attr_accessor :name
+
+        # @!attribute [rw] timezone_id
+        #   @return [String, nil] The account's timezone identifier.
+        attr_accessor :timezone_id
+
+        # @!attribute [rw] message_template_namespace
+        #   @return [String, nil] The namespace the account's templates live in.
+        attr_accessor :message_template_namespace
+
+        # @!attribute [rw] account_review_status
+        #   @return [String, nil] One of {ReviewStatuses::ALL}.
+        attr_accessor :account_review_status
+
+        # @!attribute [rw] business_verification_status
+        #   @return [String, nil] One of {VerificationStatuses::ALL}.
+        attr_accessor :business_verification_status
+
+        # @!attribute [rw] country
+        #   @return [String, nil] The account's country code.
+        attr_accessor :country
+
+        # @!attribute [rw] ownership_type
+        #   @return [String, nil] One of {OwnershipTypes::ALL}.
+        attr_accessor :ownership_type
+
+        # @!attribute [rw] primary_business_location
+        #   @return [String, nil] The account's primary business location.
+        attr_accessor :primary_business_location
+
+        # @param id [String, nil]
+        # @param name [String, nil]
+        # @param timezone_id [String, nil]
+        # @param message_template_namespace [String, nil]
+        # @param account_review_status [String, nil]
+        # @param business_verification_status [String, nil]
+        # @param country [String, nil]
+        # @param ownership_type [String, nil]
+        # @param primary_business_location [String, nil]
+        def initialize(id: nil, name: nil, timezone_id: nil, message_template_namespace: nil,
+          account_review_status: nil, business_verification_status: nil, country: nil,
+          ownership_type: nil, primary_business_location: nil)
+          @id = id
+          @name = name
+          @timezone_id = timezone_id
+          @message_template_namespace = message_template_namespace
+          @account_review_status = account_review_status
+          @business_verification_status = business_verification_status
+          @country = country
+          @ownership_type = ownership_type
+          @primary_business_location = primary_business_location
+        end
+
+        class << self
+          # @param response [Hash, nil] The parsed response body.
+          # @return [Details]
+          def deserialize(response)
+            response ||= {}
+
+            new(
+              id: response["id"],
+              name: response["name"],
+              timezone_id: response["timezone_id"],
+              message_template_namespace: response["message_template_namespace"],
+              account_review_status: response["account_review_status"],
+              business_verification_status: response["business_verification_status"],
+              country: response["country"],
+              ownership_type: response["ownership_type"],
+              primary_business_location: response["primary_business_location"]
+            )
+          end
+        end
+
+        # @return [Boolean] Whether Meta has approved the account.
+        def approved?
+          account_review_status == ReviewStatuses::APPROVED
+        end
+
+        # @return [Boolean] Whether the business behind the account is verified.
+        def verified?
+          business_verification_status == VerificationStatuses::VERIFIED
+        end
+
+        # @return [Boolean] Whether the account belongs to your own business, rather
+        #   than to a client or a partner acting on one's behalf.
+        def self_owned?
+          ownership_type == OwnershipTypes::SELF
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number/account/get.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Account
+      # Reads a WhatsApp Business Account's details: its configuration, review and
+      # verification status, and ownership.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/whatsapp-business-account-api
+      class Get
+        extend ResponseHandling
+        extend Transport
+
+        # The fields Meta documents for this node. Offered for convenience, not
+        # enforcement — {.call} deliberately does not validate `fields` against this
+        # list (nor does {Whatsapp::SubscribedApp::List}), so a field Meta adds later
+        # works without a gem release.
+        module Fields
+          ID = "id"
+          NAME = "name"
+          TIMEZONE_ID = "timezone_id"
+          MESSAGE_TEMPLATE_NAMESPACE = "message_template_namespace"
+          ACCOUNT_REVIEW_STATUS = "account_review_status"
+          BUSINESS_VERIFICATION_STATUS = "business_verification_status"
+          COUNTRY = "country"
+          OWNERSHIP_TYPE = "ownership_type"
+          PRIMARY_BUSINESS_LOCATION = "primary_business_location"
+
+          ALL = [ID, NAME, TIMEZONE_ID, MESSAGE_TEMPLATE_NAMESPACE, ACCOUNT_REVIEW_STATUS,
+                 BUSINESS_VERIFICATION_STATUS, COUNTRY, OWNERSHIP_TYPE, PRIMARY_BUSINESS_LOCATION,].freeze
+        end
+
+        class << self
+          # @example Read everything Meta publishes for the account
+          #   Get.call(fields: Get::Fields::ALL)
+          # @param client [Whatsapp::Client] The WhatsApp client instance.
+          # @param fields [Array<String>, String, nil] Restrict the response to these
+          #   fields; see {Fields::ALL}. Omitted entirely when nil, in which case Meta
+          #   returns only its own defaults (`id` and `name`).
+          # @return [Details]
+          # @raise [Error] if no WABA ID is configured, or the request fails.
+          def call(client: Client.new, fields: nil)
+            params = fields ? { fields: Array(fields).join(",") } : {}
+            response = client.connection.get(node_path(client), params:)
+
+            Details.deserialize(
+              parse_json(handle_response!(response, error_class: Error, action: "get business account details"))
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number/account/transport.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Account
+      # The one piece shared by {Get} and {Update}: both address the WABA node itself,
+      # differing only in HTTP verb and body. Extended (not included) since those
+      # classes are class-method-only.
+      #
+      # Deliberately separate from {BusinessPhoneNumber::Transport}, which this shadows
+      # by lexical scope inside {Account}. That one guards `phone_id` and always appends
+      # an edge segment; this addresses `waba_id` and no edge at all. Both delegate the
+      # guard and its wording to {Whatsapp::PathBuilding}, so the method names are now the
+      # whole of the difference — `node_path` here, `edge_path` there, so the two can never
+      # be confused at a call site.
+      module Transport
+        include Whatsapp::PathBuilding
+
+      private
+
+        # @param client [Whatsapp::Client]
+        # @return [String] The versioned path to the WABA node, with no edge segment.
+        # @raise [Error] if no WABA ID is configured.
+        def node_path(client)
+          scoped_path(client, :waba_id, error_class: Error, purpose: "business account details")
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number/account/update.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Account
+      # Updates a WhatsApp Business Account's name or timezone.
+      #
+      # A validated instance rather than a bare class method (unlike {Get}, which has
+      # nothing to check): Meta documents `name` as a non-empty string, and since both
+      # fields are optional an all-nil call would spend a request to change nothing.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/whatsapp-business-account-api
+      class Update
+        include ActiveModel::Validations
+        extend ResponseHandling
+        extend Transport
+
+        # @!attribute [rw] name
+        #   @return [String, nil] The account's new name.
+        attr_accessor :name
+
+        # @!attribute [rw] timezone_id
+        #   @return [String, nil] The account's new timezone identifier.
+        attr_accessor :timezone_id
+
+        validate :validate_any_attribute_present
+        validates :name, presence: true, allow_nil: true
+        validates :timezone_id, presence: true, allow_nil: true
+
+        # @param name [String, nil] The account's new name. Meta rejects an empty
+        #   string, so a blank value fails here rather than at the API.
+        # @param timezone_id [String, nil] The account's new timezone identifier. Meta
+        #   publishes no enum for this field, so only presence is checked.
+        # @raise [ActiveModel::ValidationError] if both are nil, or either is blank.
+        def initialize(name: nil, timezone_id: nil)
+          @name = name
+          @timezone_id = timezone_id
+
+          validate!
+        end
+
+        # @return [Hash] The update payload. Both fields are optional, so an omitted
+        #   one is compacted away rather than sent as null — which Meta would read as
+        #   an instruction to blank it.
+        def serialize
+          { name:, timezone_id: }.compact
+        end
+
+        class << self
+          # @param client [Whatsapp::Client] The WhatsApp client instance.
+          # @param name [String, nil] See {#initialize}.
+          # @param timezone_id [String, nil] See {#initialize}.
+          # @return [BusinessPhoneNumber::Response]
+          # @raise [ActiveModel::ValidationError] if no attribute is given, or one is blank.
+          # @raise [Error] if no WABA ID is configured, or the request fails.
+          def call(client: Client.new, name: nil, timezone_id: nil)
+            body = new(name:, timezone_id:).serialize
+            response = client.connection.post(node_path(client), json: body)
+
+            BusinessPhoneNumber::Response.deserialize(
+              parse_json(handle_response!(response, error_class: Error, action: "update business account"))
+            )
+          end
+        end
+
+      private
+
+        # @return [void]
+        def validate_any_attribute_present
+          return unless name.nil? && timezone_id.nil?
+
+          errors.add(:base, "at least one of name or timezone_id must be provided")
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number/account.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    # Reads and updates the WhatsApp Business Account node itself — the account a
+    # business phone number belongs to, as opposed to the number's own onboarding
+    # state that the rest of this module drives.
+    #
+    # This is the one part of {Whatsapp::BusinessPhoneNumber} that addresses `waba_id`
+    # rather than `phone_id`, so it carries its own {Transport} and cannot share
+    # {BusinessPhoneNumber::Transport}. It is also the only endpoint pair here that
+    # touches the account rather than the number: {Get} reads review, verification, and
+    # ownership state; {Update} renames the account or moves its timezone.
+    #
+    # Distinct from {Whatsapp::SubscribedApp}, which addresses the same `waba_id` but
+    # only toggles webhook delivery, and from {Whatsapp::MessageTemplates}, which
+    # manages the templates hanging off that account.
+    # See `docs/business_phone_number/account.md`.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/whatsapp-business-account-api
+    module Account
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number/profile/details.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Profile
+      # The business profile returned by {Get}.
+      #
+      # Every field arrives only when asked for via `fields`, so every attribute tolerates
+      # being absent. Nothing is validated or normalized on the way in — this is read-side
+      # data, and a `vertical` Meta adds later must still round-trip untouched. Compare
+      # against {Verticals::ALL} rather than expecting this class to have rejected an unknown
+      # value, the same reasoning as {Account::Details}' statuses and
+      # {Whatsapp::MessageTemplates::Response::Node}'s raw components.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/whatsapp-business-profile-api
+      class Details
+        # @!attribute [rw] messaging_product
+        #   @return [String, nil] The messaging service, always `"whatsapp"` in practice.
+        attr_accessor :messaging_product
+
+        # @!attribute [rw] about
+        #   @return [String, nil] The text shown in the profile's About section.
+        attr_accessor :about
+
+        # @!attribute [rw] address
+        #   @return [String, nil] The business's physical address.
+        attr_accessor :address
+
+        # @!attribute [rw] description
+        #   @return [String, nil] The business description.
+        attr_accessor :description
+
+        # @!attribute [rw] email
+        #   @return [String, nil] The business's contact email address.
+        attr_accessor :email
+
+        # @!attribute [rw] profile_picture_url
+        #   @return [String, nil] The URL of the profile picture.
+        attr_accessor :profile_picture_url
+
+        # @!attribute [rw] websites
+        #   @return [Array<String>, nil] The business's website URLs.
+        attr_accessor :websites
+
+        # @!attribute [rw] vertical
+        #   @return [String, nil] One of {Verticals::ALL}, as sent by Meta.
+        attr_accessor :vertical
+
+        # @param messaging_product [String, nil]
+        # @param about [String, nil]
+        # @param address [String, nil]
+        # @param description [String, nil]
+        # @param email [String, nil]
+        # @param profile_picture_url [String, nil]
+        # @param websites [Array<String>, nil]
+        # @param vertical [String, nil]
+        def initialize(messaging_product: nil, about: nil, address: nil, description: nil,
+          email: nil, profile_picture_url: nil, websites: nil, vertical: nil)
+          @messaging_product = messaging_product
+          @about = about
+          @address = address
+          @description = description
+          @email = email
+          @profile_picture_url = profile_picture_url
+          @websites = websites
+          @vertical = vertical
+        end
+
+        class << self
+          # @param response [Hash, nil] The parsed response body, envelope included.
+          # @return [Details]
+          def deserialize(response)
+            profile = unwrap(response)
+
+            new(
+              messaging_product: profile["messaging_product"],
+              about: profile["about"],
+              address: profile["address"],
+              description: profile["description"],
+              email: profile["email"],
+              profile_picture_url: profile["profile_picture_url"],
+              websites: profile["websites"],
+              vertical: profile["vertical"]
+            )
+          end
+
+        private
+
+          # Digs the profile out of Meta's `data` envelope.
+          #
+          # The reference documents the entry as wrapping the profile in `business_profile`,
+          # while live responses are observed to carry the fields directly; both are read
+          # rather than betting on one. Only the first entry matters — a phone number has
+          # exactly one profile.
+          # @param response [Hash, nil]
+          # @return [Hash]
+          def unwrap(response)
+            entry = Array((response || {})["data"]).first || {}
+
+            entry["business_profile"] || entry
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number/profile/get.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Profile
+      # Reads a business profile: its about text, description, contact details, websites,
+      # industry vertical, and profile picture.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/whatsapp-business-profile-api
+      class Get
+        extend ResponseHandling
+        extend Transport
+
+        module Defaults
+          EDGE = "whatsapp_business_profile"
+        end
+
+        # The fields Meta documents for this edge. Offered for convenience, not
+        # enforcement — {.call} deliberately does not validate `fields` against this list
+        # (nor do {Account::Get} or {Whatsapp::SubscribedApp::List}), so a field Meta adds
+        # later works without a gem release.
+        module Fields
+          MESSAGING_PRODUCT = "messaging_product"
+          ABOUT = "about"
+          ADDRESS = "address"
+          DESCRIPTION = "description"
+          EMAIL = "email"
+          PROFILE_PICTURE_URL = "profile_picture_url"
+          WEBSITES = "websites"
+          VERTICAL = "vertical"
+
+          ALL = [MESSAGING_PRODUCT, ABOUT, ADDRESS, DESCRIPTION, EMAIL, PROFILE_PICTURE_URL,
+                 WEBSITES, VERTICAL,].freeze
+        end
+
+        class << self
+          # @example Read everything Meta publishes for the profile
+          #   Get.call(fields: Get::Fields::ALL)
+          # @param client [Whatsapp::Client] The WhatsApp client instance.
+          # @param fields [Array<String>, String, nil] Restrict the response to these
+          #   fields; see {Fields::ALL}. Omitted entirely when nil, in which case Meta
+          #   returns only its own defaults.
+          # @return [Details]
+          # @raise [Error] if no phone number ID is configured, or the request fails.
+          def call(client: Client.new, fields: nil)
+            params = fields ? { fields: Array(fields).join(",") } : {}
+            response = client.connection.get(edge_path(client, Defaults::EDGE), params:)
+
+            Details.deserialize(
+              parse_json(handle_response!(response, error_class: Error, action: "get business profile details"))
+            )
+          end
+        end
+      end
+    end
+  end
+end