ruby-whatsapp 0.4.0 → 0.4.2

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

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Profile
+      # Updates a business profile: its about text, description, contact details, websites,
+      # industry vertical, and profile picture.
+      #
+      # A validated instance rather than a bare class method (unlike {Get}, which has nothing
+      # to check): Meta documents a closed vertical enum and per-field character limits, and
+      # since every field is optional an all-nil call would spend a request to change nothing.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/whatsapp-business-profile-api
+      class Update
+        include ActiveModel::Validations
+        extend ResponseHandling
+        extend Transport
+
+        module Defaults
+          MESSAGING_PRODUCT = "whatsapp"
+          EDGE = "whatsapp_business_profile"
+        end
+
+        # The character and count limits Meta documents for a business profile.
+        module Limits
+          ABOUT = 139
+          ADDRESS = 256
+          DESCRIPTION = 512
+          EMAIL = 128
+          WEBSITES = 2
+        end
+
+        # Every updatable field, in payload order. Drives both the "change something"
+        # guard and its message, so the two cannot drift apart.
+        ATTRIBUTES = %i[about address description email vertical websites profile_picture_handle].freeze
+
+        # @!attribute [rw] about
+        #   @return [String, nil] The profile's about text, at most {Limits::ABOUT} characters.
+        attr_accessor :about
+
+        # @!attribute [rw] address
+        #   @return [String, nil] The business's address, at most {Limits::ADDRESS} characters.
+        attr_accessor :address
+
+        # @!attribute [rw] description
+        #   @return [String, nil] The business description, at most {Limits::DESCRIPTION} characters.
+        attr_accessor :description
+
+        # @!attribute [rw] email
+        #   @return [String, nil] The contact email, at most {Limits::EMAIL} characters.
+        attr_accessor :email
+
+        # @!attribute [rw] vertical
+        #   @return [String, nil] One of {Verticals::ALL}.
+        attr_accessor :vertical
+
+        # @!attribute [rw] websites
+        #   @return [Array<String>, nil] At most {Limits::WEBSITES} URLs.
+        attr_accessor :websites
+
+        # @!attribute [rw] profile_picture_handle
+        #   @return [String, nil] A picture handle from Meta's Resumable Upload API.
+        attr_accessor :profile_picture_handle
+
+        validate :validate_any_attribute_present
+        validate :validate_websites_limit
+        validates :about, length: { maximum: Limits::ABOUT }, allow_nil: true
+        validates :address, length: { maximum: Limits::ADDRESS }, allow_nil: true
+        validates :description, length: { maximum: Limits::DESCRIPTION }, allow_nil: true
+        validates :email, length: { maximum: Limits::EMAIL }, allow_nil: true
+        validates :vertical, inclusion: { in: Verticals::ALL }, allow_nil: true
+        validates :profile_picture_handle, presence: true, allow_nil: true
+
+        # @param about [String, nil] See {#about}.
+        # @param address [String, nil] See {#address}.
+        # @param description [String, nil] See {#description}.
+        # @param email [String, nil] Length only — Meta validates the address itself
+        #   server-side, and a format check here would reject valid exotic addresses.
+        # @param vertical [String, Symbol, nil] One of {Verticals::ALL}, either casing.
+        # @param websites [Array<String>, nil] At most {Limits::WEBSITES} URLs. An empty
+        #   array is a deliberate instruction to clear the list, not an omission.
+        # @param profile_picture_handle [String, nil] Opaque to this gem; presence only.
+        # @raise [ActiveModel::ValidationError] if every field is nil, or one breaks a
+        #   documented limit.
+        def initialize(about: nil, address: nil, description: nil, email: nil, vertical: nil,
+          websites: nil, profile_picture_handle: nil)
+          @about = about
+          @address = address
+          @description = description
+          @email = email
+          @vertical = Verticals.normalize(vertical)
+          @websites = websites
+          @profile_picture_handle = profile_picture_handle
+
+          validate!
+        end
+
+        # @return [Hash] The update payload. `messaging_product` is documented required so it
+        #   is always sent; every other field is optional and an omitted one is compacted away
+        #   rather than sent as null, which Meta would read as an instruction to blank it.
+        #   An empty `websites` array survives compaction on purpose — that *is* the clear.
+        def serialize
+          { messaging_product: Defaults::MESSAGING_PRODUCT, about:, address:, description:,
+            email:, vertical:, websites:, profile_picture_handle:, }.compact
+        end
+
+        class << self
+          # @param client [Whatsapp::Client] The WhatsApp client instance.
+          # @param about [String, nil] See {#initialize}.
+          # @param address [String, nil] See {#initialize}.
+          # @param description [String, nil] See {#initialize}.
+          # @param email [String, nil] See {#initialize}.
+          # @param vertical [String, Symbol, nil] See {#initialize}.
+          # @param websites [Array<String>, nil] See {#initialize}.
+          # @param profile_picture_handle [String, nil] See {#initialize}.
+          # @return [BusinessPhoneNumber::Response]
+          # @raise [ActiveModel::ValidationError] if no field is given, or one is invalid.
+          # @raise [Error] if no phone number ID is configured, or the request fails.
+          def call(client: Client.new, about: nil, address: nil, description: nil, email: nil,
+            vertical: nil, websites: nil, profile_picture_handle: nil)
+            body = new(about:, address:, description:, email:, vertical:, websites:,
+              profile_picture_handle:).serialize
+            response = client.connection.post(edge_path(client, Defaults::EDGE), json: body)
+
+            BusinessPhoneNumber::Response.deserialize(
+              parse_json(handle_response!(response, error_class: Error, action: "update business profile"))
+            )
+          end
+        end
+
+      private
+
+        # @return [void]
+        def validate_any_attribute_present
+          return if ATTRIBUTES.any? { |attribute| !public_send(attribute).nil? }
+
+          errors.add(:base, "at least one of #{ATTRIBUTES.join(', ')} must be provided")
+        end
+
+        # @return [void]
+        def validate_websites_limit
+          return if websites.nil? || websites.size <= Limits::WEBSITES
+
+          errors.add(:base, "websites accepts at most #{Limits::WEBSITES} URLs")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Profile
+      # The industry verticals Meta publishes for a business profile.
+      #
+      # Its own file rather than nested inside {Update}, since two classes use it: {Update}
+      # validates against it and {Details} exposes the raw value for comparison against it.
+      # That follows {Whatsapp::MessageTemplates::Categories}' precedent rather than
+      # {Register::DataLocalizationRegions}', which has a single consumer.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/whatsapp-business-profile-api
+      module Verticals
+        ALCOHOL = "ALCOHOL"
+        APPAREL = "APPAREL"
+        AUTO = "AUTO"
+        BEAUTY = "BEAUTY"
+        EDU = "EDU"
+        ENTERTAIN = "ENTERTAIN"
+        EVENT_PLAN = "EVENT_PLAN"
+        FINANCE = "FINANCE"
+        GOVT = "GOVT"
+        GROCERY = "GROCERY"
+        HEALTH = "HEALTH"
+        HOTEL = "HOTEL"
+        NONPROFIT = "NONPROFIT"
+        ONLINE_GAMBLING = "ONLINE_GAMBLING"
+        OTC_DRUGS = "OTC_DRUGS"
+        OTHER = "OTHER"
+        PHYSICAL_GAMBLING = "PHYSICAL_GAMBLING"
+        PROF_SERVICES = "PROF_SERVICES"
+        RESTAURANT = "RESTAURANT"
+        RETAIL = "RETAIL"
+        TRAVEL = "TRAVEL"
+
+        ALL = [ALCOHOL, APPAREL, AUTO, BEAUTY, EDU, ENTERTAIN, EVENT_PLAN, FINANCE, GOVT,
+               GROCERY, HEALTH, HOTEL, NONPROFIT, ONLINE_GAMBLING, OTC_DRUGS, OTHER,
+               PHYSICAL_GAMBLING, PROF_SERVICES, RESTAURANT, RETAIL, TRAVEL,].freeze
+
+        # Normalizes caller input to a canonical uppercase vertical.
+        # Unrecognized values are returned untouched so the inclusion validator can
+        # report them, matching {Register::DataLocalizationRegions.normalize}.
+        # @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
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    # Reads and updates a business phone number's **business profile** — the public card a
+    # WhatsApp user sees before they reply: the about line, description, address, email,
+    # websites, industry vertical, and profile picture.
+    #
+    # Unlike {Account}, this is not an exception to the module's `phone_id` rule: Meta exposes
+    # the profile as an edge on the phone number itself
+    # (`GET`/`POST /{phone_id}/whatsapp_business_profile`), so {Get} and {Update} address the
+    # same ID the onboarding actions do and reuse {BusinessPhoneNumber::Transport} unchanged.
+    #
+    # Distinct from {Account}, which describes the *account* a number belongs to rather than
+    # how that number presents itself, and from {Whatsapp::Messages}, which is what actually
+    # reaches a user once the profile is set.
+    # See `docs/business_phone_number/profile.md`.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/whatsapp-business-profile-api
+    module Profile
+    end
+  end
+end

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

@@ -2,11 +2,11 @@
 
 module Whatsapp
   module BusinessPhoneNumber
-    # The response shared by all four phone-number actions: `{success}`, with an
+    # The response shared by every write action in this module: `{success}`, with an
     # optional `id` that only `VerifyCode` ever populates. One class covers all of
     # them — unlike {Whatsapp::SubscribedApp}'s `Response::*` namespace — since
-    # {Register}, {Deregister}, {RequestCode}, and {VerifyCode} all return this same
-    # shape, `id` included or not.
+    # {Register}, {Deregister}, {RequestCode}, {VerifyCode}, {Account::Update}, and
+    # {Profile::Update} all return this same shape, `id` included or not.
     # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/registration
     class Response
       # @!attribute [rw] success

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

@@ -2,26 +2,25 @@
 
 module Whatsapp
   module BusinessPhoneNumber
-    # The one piece shared by {Register}, {Deregister}, {RequestCode}, and
-    # {VerifyCode}: all four address the same phone-number-scoped resource, differing
-    # only in edge name and body. Extended (not included) because {#edge_path} is used
-    # from class-level `.call` methods (as a private class method).
+    # The one piece shared by {Register}, {Deregister}, {RequestCode}, {VerifyCode}, and
+    # {Profile}: all of them address a phone-number-scoped edge, differing only in edge name
+    # and body. Extended (not included) because {#edge_path} is used from class-level `.call`
+    # methods (as a private class method).
+    #
+    # The guard itself and its message live in {Whatsapp::PathBuilding}, shared with every
+    # other ID-scoped feature; what stays here is the ID this module addresses.
     module Transport
+      include Whatsapp::PathBuilding
+
     private
 
       # @param client [Whatsapp::Client]
       # @param action [String] The edge to address ("register", "deregister",
-      #   "request_code", or "verify_code").
+      #   "request_code", "verify_code", or "whatsapp_business_profile").
       # @return [String] The versioned path to the phone number's action edge.
       # @raise [Error] if no phone number ID is configured.
       def edge_path(client, action)
-        if client.phone_id.nil? || client.phone_id.to_s.empty?
-          raise Error,
-            "phone_id is required for the #{action} edge; " \
-              "set it via Whatsapp.configure or Client.new(phone_id:)"
-        end
-
-        client.path_for(client.phone_id, action)
+        scoped_path(client, :phone_id, action, error_class: Error, purpose: "the #{action} edge")
       end
     end
   end

data/lib/ruby/whatsapp/business_phone_number.rb

@@ -8,13 +8,20 @@ module Whatsapp
   # the first place. It is a different concern from {Whatsapp::SubscribedApp}, which
   # turns webhook delivery on and off for a whole WhatsApp Business Account: this
   # module is per phone number and is a prerequisite for messaging itself, not just
-  # for notifications. Addresses `phone_id`, like {Whatsapp::Media} and
-  # {Whatsapp::Messages}, not `waba_id`.
+  # for notifications. The onboarding actions address `phone_id`, like
+  # {Whatsapp::Media} and {Whatsapp::Messages}.
   #
   # The full flow, in order: {RequestCode} -> {VerifyCode} -> {Register}, with
   # {Deregister} as the reverse switch.
-  # See `lib/ruby/whatsapp/business_phone_number/CLAUDE.md` and
-  # `docs/business-phone-number-api.md`.
+  #
+  # {Profile} reads and updates the public card a WhatsApp user sees before they reply.
+  # It addresses `phone_id` like the onboarding actions above, so it shares their transport.
+  #
+  # {Account} is the one exception to the `phone_id` rule: it reads and updates the
+  # WhatsApp Business Account a number belongs to, so it addresses `waba_id` and
+  # carries its own transport.
+  # See `lib/ruby/whatsapp/business_phone_number/CLAUDE.md`,
+  # `docs/business_phone_number/README.md`, and `docs/business_phone_number/profile.md`.
   # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/registration
   module BusinessPhoneNumber
     class Error < Whatsapp::Error; end

data/lib/ruby/whatsapp/message_templates.rb

@@ -25,6 +25,7 @@ module Whatsapp
   #   templates.find(template_id: created.id).status # => "PENDING"
   # Source: https://developers.facebook.com/docs/graph-api/reference/whats-app-business-account/message_templates/
   class MessageTemplates
+    include PathBuilding
     include ResponseHandling
 
     class TemplateError < Whatsapp::Error; end
@@ -204,12 +205,7 @@ module Whatsapp
     # @return [String] The versioned path for a WABA-scoped edge.
     # @raise [TemplateError] if no WABA ID is configured.
     def edge_path(edge)
-      if blank_value?(client.waba_id)
-        raise TemplateError,
-          "waba_id is required for template management; set it via Whatsapp.configure or Client.new(waba_id:)"
-      end
-
-      client.path_for(client.waba_id, edge)
+      scoped_path(client, :waba_id, edge, error_class: TemplateError, purpose: "template management")
     end
 
     # @return [Hash] Only the editable fields that were supplied.

data/lib/ruby/whatsapp/path_building.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  # The ID guard and path build shared by every WABA- or phone-number-scoped feature.
+  #
+  # Each feature keeps its own transport with a named method — {Whatsapp::SubscribedApp::Transport}'s
+  # `edge_path`, {Whatsapp::BusinessPhoneNumber::Account::Transport}'s `node_path` — since those
+  # names are what keep an edge and a node from being confused at a call site. This holds only
+  # the part that was identical across all of them: refusing to address an unconfigured ID, and
+  # phrasing that refusal the same way every time.
+  module PathBuilding
+  private
+
+    # @param client [Whatsapp::Client]
+    # @param id_name [Symbol] The client attribute to address (`:waba_id` or `:phone_id`).
+    # @param segments [Array<String>] Edge segments after the ID; pass none to address the node itself.
+    # @param error_class [Class] The feature's own error class, never {Whatsapp::RequestError}.
+    # @param purpose [String] What the caller was reaching for, e.g. `"subscribed apps"`.
+    # @return [String] The versioned path.
+    # @raise [Whatsapp::Error] the given error_class, if the ID is not configured.
+    def scoped_path(client, id_name, *segments, error_class:, purpose:)
+      id = client.public_send(id_name)
+
+      if id.nil? || id.to_s.empty?
+        raise error_class,
+          "#{id_name} is required for #{purpose}; " \
+            "set it via Whatsapp.configure or Client.new(#{id_name}:)"
+      end
+
+      client.path_for(id, *segments)
+    end
+  end
+end

data/lib/ruby/whatsapp/subscribed_app/transport.rb

@@ -5,18 +5,19 @@ module Whatsapp
     # The one piece shared by {List}, {Subscribe}, and {Unsubscribe}: all three address
     # the same WABA-scoped edge, differing only in HTTP verb and body. Extended (not
     # included) since those classes are class-method-only.
+    #
+    # The guard itself and its message live in {Whatsapp::PathBuilding}, shared with every
+    # other ID-scoped feature; what stays here is the edge this module addresses.
     module Transport
+      include Whatsapp::PathBuilding
+
     private
 
       # @param client [Whatsapp::Client]
       # @return [String] The versioned path to the `subscribed_apps` edge.
       # @raise [Error] if no WABA ID is configured.
       def edge_path(client)
-        if client.waba_id.nil? || client.waba_id.to_s.empty?
-          raise Error, "waba_id is required for subscribed apps; set it via Whatsapp.configure or Client.new(waba_id:)"
-        end
-
-        client.path_for(client.waba_id, "subscribed_apps")
+        scoped_path(client, :waba_id, "subscribed_apps", error_class: Error, purpose: "subscribed apps")
       end
     end
   end

data/lib/ruby/whatsapp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Whatsapp
-  VERSION = "0.4.0"
+  VERSION = "0.4.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-whatsapp
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Raniery
@@ -82,9 +82,70 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/README.md
+- docs/business_phone_number/README.md
+- docs/business_phone_number/account.md
+- docs/business_phone_number/profile.md
+- docs/configuration.md
+- docs/errors.md
+- docs/media/README.md
+- docs/message_templates/README.md
+- docs/message_templates/authentication.md
+- docs/message_templates/carousel.md
+- docs/message_templates/components.md
+- docs/message_templates/library.md
+- docs/message_templates/limited_time_offer.md
+- docs/message_templates/responses.md
+- docs/message_templates/standard.md
+- docs/messages/README.md
+- docs/messages/address.md
+- docs/messages/audio.md
+- docs/messages/contacts.md
+- docs/messages/document.md
+- docs/messages/image.md
+- docs/messages/interactive.md
+- docs/messages/location.md
+- docs/messages/location_request.md
+- docs/messages/mark_message_as_read.md
+- docs/messages/reaction.md
+- docs/messages/sticker.md
+- docs/messages/template.md
+- docs/messages/text.md
+- docs/messages/video.md
+- docs/subscribed_app/README.md
+- docs/webhooks/README.md
+- docs/webhooks/account_alerts.md
+- docs/webhooks/account_review_update.md
+- docs/webhooks/account_update.md
+- docs/webhooks/automatic_events.md
+- docs/webhooks/business_capability_update.md
+- docs/webhooks/history.md
+- docs/webhooks/message_template_components_update.md
+- docs/webhooks/message_template_quality_update.md
+- docs/webhooks/message_template_status_update.md
+- docs/webhooks/messages.md
+- docs/webhooks/partner_solutions.md
+- docs/webhooks/payment_configuration_update.md
+- docs/webhooks/phone_number_name_update.md
+- docs/webhooks/phone_number_quality_update.md
+- docs/webhooks/security.md
+- docs/webhooks/smb_app_state_sync.md
+- docs/webhooks/smb_message_echoes.md
+- docs/webhooks/template_category_update.md
+- docs/webhooks/user_preferences.md
 - lib/ruby/whatsapp.rb
 - lib/ruby/whatsapp/business_phone_number.rb
+- lib/ruby/whatsapp/business_phone_number/account.rb
+- lib/ruby/whatsapp/business_phone_number/account/details.rb
+- lib/ruby/whatsapp/business_phone_number/account/get.rb
+- lib/ruby/whatsapp/business_phone_number/account/transport.rb
+- lib/ruby/whatsapp/business_phone_number/account/update.rb
 - lib/ruby/whatsapp/business_phone_number/deregister.rb
+- lib/ruby/whatsapp/business_phone_number/profile.rb
+- lib/ruby/whatsapp/business_phone_number/profile/details.rb
+- lib/ruby/whatsapp/business_phone_number/profile/get.rb
+- lib/ruby/whatsapp/business_phone_number/profile/update.rb
+- lib/ruby/whatsapp/business_phone_number/profile/verticals.rb
 - lib/ruby/whatsapp/business_phone_number/register.rb
 - lib/ruby/whatsapp/business_phone_number/request_code.rb
 - lib/ruby/whatsapp/business_phone_number/response.rb
@@ -175,6 +236,7 @@ files:
 - lib/ruby/whatsapp/messages/template/parameter.rb
 - lib/ruby/whatsapp/messages/text.rb
 - lib/ruby/whatsapp/messages/video.rb
+- lib/ruby/whatsapp/path_building.rb
 - lib/ruby/whatsapp/railtie.rb
 - lib/ruby/whatsapp/request_error.rb
 - lib/ruby/whatsapp/response_handling.rb