ruby-whatsapp 0.4.0 → 0.6.1

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,26 @@
 
 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},
+    # {Profile}, {Username}, and {ContactBook}: 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", "whatsapp_business_profile", "username",
+      #   "username_suggestions", or "contact_book").
       # @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/username/claim.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Username
+      # Claims a business username for a phone number, or moves one you already hold onto
+      # a different number of yours.
+      #
+      # A validated instance rather than a bare class method: Meta publishes the username
+      # format as a set of client-side rules, and the edge is rate limited, so a request
+      # that was never going to be accepted should not be spent. Named {Claim} rather than
+      # `Create`/`Update`/`Set` — posting again *replaces* the current username, `Update`
+      # would suggest the partial-update semantics of {Profile::Update}, and `Set` would
+      # shadow `::Set` inside this namespace.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
+      class Claim
+        include ActiveModel::Validations
+        extend ResponseHandling
+        extend Transport
+
+        module Defaults
+          EDGE = "username"
+          MIN_LENGTH = 3
+          MAX_LENGTH = 35
+          CHARSET_PATTERN = /\A[a-z0-9._]+\z/
+          LETTER_PATTERN = /[a-z]/
+          RESERVED_PREFIX = "www"
+        end
+
+        # What happens when the username is already in use on another business phone
+        # number in the *same* portfolio.
+        module TransferActions
+          NONE = "none"
+          FORCE_TRANSFER = "force_transfer"
+
+          ALL = [NONE, FORCE_TRANSFER].freeze
+
+          # Normalizes caller input to Meta's documented casing, which is lowercase here —
+          # unlike this module's other enums. Unrecognized values are returned untouched so
+          # the inclusion validator can report them.
+          # @param value [String, Symbol, nil]
+          # @return [String, nil]
+          def self.normalize(value)
+            return if value.nil?
+
+            candidate = value.to_s.downcase
+            ALL.include?(candidate) ? candidate : value.to_s
+          end
+        end
+
+        # The domain-like endings Meta lists. **Its list is explicitly open-ended** ("and
+        # so on"), so this cannot be complete: a suffix outside it is rejected server-side
+        # with error `100` instead. Checked locally anyway, because catching the common
+        # cases without spending a rate-limited request is worth more than the false sense
+        # of completeness costs.
+        DOMAIN_SUFFIXES = %w[.com .org .net .int .edu .gov .mil .us .in .html].freeze
+
+        # @!attribute [rw] username
+        #   @return [String] The desired username, downcased.
+        attr_accessor :username
+
+        # @!attribute [rw] transfer_action
+        #   @return [String] One of {TransferActions::ALL}.
+        attr_accessor :transfer_action
+
+        validate :validate_username_format
+        validates :username, presence: true
+        # Length is nil-exempt so a missing username reports only "can't be blank" — the
+        # presence validator above is what must catch nil, and a shared `allow_nil` would
+        # have exempted it too.
+        validates :username, length: { minimum: Defaults::MIN_LENGTH, maximum: Defaults::MAX_LENGTH },
+          allow_nil: true
+        validates :transfer_action, inclusion: { in: TransferActions::ALL }
+
+        # @param username [String] The desired username. Meta compares usernames
+        #   case-insensitively, so a mixed-case value is downcased here rather than
+        #   rejected — `"JaspersMarket"` and `"jaspersmarket"` are the same name, and
+        #   refusing one Meta would have accepted is the failure mode this module avoids.
+        #   `.` and `_` *are* significant: `myid`, `my.id`, and `my_id` are three names.
+        # @param transfer_action [String, Symbol] `"none"` (the default) fails with error
+        #   `147005` if another of your numbers holds the name; `"force_transfer"` moves it.
+        # @raise [ActiveModel::ValidationError] if the username breaks a documented rule.
+        def initialize(username:, transfer_action: TransferActions::NONE)
+          @username = username&.to_s&.downcase
+          @transfer_action = TransferActions.normalize(transfer_action)
+
+          validate!
+        end
+
+        # @return [Hash] The claim payload. `transfer_action` is always sent rather than
+        #   compacted away when it is the default: it is a per-request behavior flag, not a
+        #   stored field, so convention 7's "nil means leave alone" does not apply — and
+        #   sending it explicitly pins the behavior if Meta ever changes its own default,
+        #   which matters for an operation whose other value takes a name off another number.
+        def serialize
+          { username:, transfer_action: }
+        end
+
+        class << self
+          # @example Move a username onto this number from another of yours
+          #   Claim.call(username: "jaspersmarket", transfer_action: :force_transfer)
+          # @param client [Whatsapp::Client] The WhatsApp client instance.
+          # @param username [String] See {#initialize}.
+          # @param transfer_action [String, Symbol] See {#initialize}.
+          # @return [Details] Carrying `status` only; `username` is `nil`, since Meta
+          #   answers with the state rather than echoing the name back.
+          # @raise [ActiveModel::ValidationError] if the username breaks a documented rule.
+          # @raise [Error] if no phone number ID is configured, or the request fails. Error
+          #   `147005` means another of your numbers holds the name — retry with
+          #   `transfer_action: "force_transfer"`. `147001` means it is unavailable,
+          #   `147002` that the portfolio's messaging limit is too low, and
+          #   `147003`/`147004` that the number must first be linked to the Facebook Page
+          #   or Instagram account already using it.
+          def call(username:, client: Client.new, transfer_action: TransferActions::NONE)
+            body = new(username:, transfer_action:).serialize
+            response = client.connection.post(edge_path(client, Defaults::EDGE), json: body)
+
+            Details.deserialize(
+              parse_json(handle_response!(response, error_class: Error, action: "claim business username"))
+            )
+          end
+        end
+
+      private
+
+        # Meta's published format rules, minus the open-ended domain-suffix list, which is
+        # handled separately.
+        # @return [void]
+        def validate_username_format
+          return if username.nil? || username.empty?
+
+          validate_charset
+          validate_has_letter
+          validate_period_placement
+          validate_not_reserved_prefix
+          validate_no_domain_suffix
+        end
+
+        # @return [void]
+        def validate_charset
+          return if username.match?(Defaults::CHARSET_PATTERN)
+
+          errors.add(:username, "may only contain a-z, 0-9, periods and underscores")
+        end
+
+        # @return [void]
+        def validate_has_letter
+          return if username.match?(Defaults::LETTER_PATTERN)
+
+          errors.add(:username, "must contain at least one letter")
+        end
+
+        # @return [void]
+        def validate_period_placement
+          errors.add(:username, "must not start or end with a period") if
+            username.start_with?(".") || username.end_with?(".")
+          errors.add(:username, "must not contain two consecutive periods") if username.include?("..")
+        end
+
+        # Read as Meta writes it: a bare `www` prefix, so `wwwidgets` is rejected too. A
+        # local false rejection is cheap and reversible; a wasted request against a rate
+        # limited edge is not, and this way the error names the exact rule.
+        # @return [void]
+        def validate_not_reserved_prefix
+          return unless username.start_with?(Defaults::RESERVED_PREFIX)
+
+          errors.add(:username, "must not start with #{Defaults::RESERVED_PREFIX}")
+        end
+
+        # @return [void]
+        def validate_no_domain_suffix
+          suffix = DOMAIN_SUFFIXES.find { |candidate| username.end_with?(candidate) }
+          return if suffix.nil?
+
+          errors.add(:username, "must not end with a domain suffix such as #{suffix}")
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number/username/delete.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Username
+      # Removes the business username from a phone number, releasing it.
+      #
+      # A bare class method with nothing to validate, like {Deregister} and {Profile::Get}:
+      # the phone number is the only input and {Transport} already guards it.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
+      class Delete
+        extend ResponseHandling
+        extend Transport
+
+        module Defaults
+          EDGE = "username"
+        end
+
+        class << self
+          # @param client [Whatsapp::Client] The WhatsApp client instance.
+          # @return [BusinessPhoneNumber::Response] Reused rather than a `Username::`-specific
+          #   class, since this endpoint answers the same bare `{success}` as
+          #   {Profile::Update} and {Account::Update}.
+          # @raise [Error] if no phone number ID is configured, or the request fails.
+          def call(client: Client.new)
+            response = client.connection.delete(edge_path(client, Defaults::EDGE))
+
+            BusinessPhoneNumber::Response.deserialize(
+              parse_json(handle_response!(response, error_class: Error, action: "delete business username"))
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Username
+      # The username state returned by {Get} and {Claim}.
+      #
+      # One class for both, rather than a response per endpoint: `GET` answers
+      # `{username, status}` and `POST` answers `{status}` — a subset, not a different
+      # shape — so `username` simply tolerates being absent, the same way
+      # {BusinessPhoneNumber::Response#id} tolerates only ever being set by {VerifyCode}.
+      # `DELETE` is the one that genuinely differs, and it reuses
+      # {BusinessPhoneNumber::Response} because a bare `{success}` is what that class is for.
+      class Details
+        # The states Meta's own responses report. Raw strings, never validated on the way
+        # in, so a value added later still round-trips — the {Account::Details} convention.
+        #
+        # The `business_username_updates` webhook reports a third state, `"deleted"`,
+        # which no API response here can return; it is deliberately absent rather than
+        # listed in an enum the write side cannot produce.
+        module Statuses
+          APPROVED = "approved"
+          RESERVED = "reserved"
+
+          ALL = [APPROVED, RESERVED].freeze
+        end
+
+        # @!attribute [rw] username
+        #   @return [String, nil] The current username. Omitted by {Claim}, which answers
+        #     with a status only — you already hold the name you passed it — and by {Get}
+        #     when the number has no username at all.
+        attr_accessor :username
+
+        # @!attribute [rw] status
+        #   @return [String, nil] One of {Statuses::ALL}.
+        attr_accessor :status
+
+        def initialize(username: nil, status: nil)
+          @username = username
+          @status = status
+        end
+
+        # @return [Boolean] Whether the username is live and visible to WhatsApp users.
+        def approved?
+          status == Statuses::APPROVED
+        end
+
+        # @return [Boolean] Whether the username is held for this number but not yet
+        #   visible — it becomes visible when Meta makes the feature generally available.
+        def reserved?
+          status == Statuses::RESERVED
+        end
+
+        class << self
+          # @param response [Hash, nil] The parsed response body.
+          # @return [Details]
+          def deserialize(response)
+            response ||= {}
+
+            new(username: response["username"], status: response["status"])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Username
+      # Reads the business username currently on a phone number, and its status.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
+      class Get
+        extend ResponseHandling
+        extend Transport
+
+        module Defaults
+          EDGE = "username"
+        end
+
+        class << self
+          # @example Check whether the username is live yet
+          #   Get.call.approved?  # => false, while still `reserved`
+          # @param client [Whatsapp::Client] The WhatsApp client instance.
+          # @return [Details] Whose `username` is `nil` if the number has none set.
+          # @raise [Error] if no phone number ID is configured, or the request fails.
+          def call(client: Client.new)
+            response = client.connection.get(edge_path(client, Defaults::EDGE))
+
+            Details.deserialize(
+              parse_json(handle_response!(response, error_class: Error, action: "get business username"))
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number/username/suggest.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Username
+      # Lists the usernames Meta has reserved for your business portfolio.
+      #
+      # Named for the verb, like {Register}/{Subscribe}, leaving the noun {Suggestions} to
+      # the value object it returns. The one action here addressing the
+      # `username_suggestions` edge rather than `username`.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
+      class Suggest
+        extend ResponseHandling
+        extend Transport
+
+        module Defaults
+          EDGE = "username_suggestions"
+        end
+
+        class << self
+          # @example Claim the first name Meta reserved for you
+          #   Username::Claim.call(username: Username::Suggest.call.first)
+          # @param client [Whatsapp::Client] The WhatsApp client instance.
+          # @return [Suggestions] Enumerable over the reserved usernames; empty if none.
+          # @raise [Error] if no phone number ID is configured, or the request fails.
+          def call(client: Client.new)
+            response = client.connection.get(edge_path(client, Defaults::EDGE))
+
+            Suggestions.deserialize(
+              parse_json(handle_response!(response, error_class: Error, action: "get username suggestions"))
+            )
+          end
+        end
+      end
+    end
+  end
+end