ruby-whatsapp 0.3.1 → 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/register.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    # Registers a business phone number with Cloud API, consuming its two-step
+    # verification PIN. This is the prerequisite for every other endpoint in this
+    # gem — a number cannot send, receive, or be otherwise addressed until it is
+    # registered.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/registration
+    class Register
+      include ActiveModel::Validations
+      extend ResponseHandling
+      extend Transport
+
+      module Defaults
+        MESSAGING_PRODUCT = "whatsapp"
+        EDGE = "register"
+        PIN_PATTERN = /\A\d{6}\z/
+      end
+
+      # The regions Meta supports for local storage, grouped as Meta's docs group
+      # them. 2-letter ISO 3166 country codes.
+      module DataLocalizationRegions
+        APAC = %w[AU ID IN JP SG KR].freeze
+        EUROPE = %w[DE CH GB].freeze
+        LATAM = %w[BR].freeze
+        MEA = %w[BH ZA AE].freeze
+        NORAM = %w[CA].freeze
+
+        ALL = [*APAC, *EUROPE, *LATAM, *MEA, *NORAM].freeze
+
+        # Normalizes caller input to a canonical uppercase region code.
+        # 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.upcase
+          ALL.include?(candidate) ? candidate : value.to_s
+        end
+      end
+
+      # @!attribute [rw] pin
+      #   @return [String] The 6-digit two-step verification PIN.
+      attr_accessor :pin
+
+      # @!attribute [rw] data_localization_region
+      #   @return [String, nil] A 2-letter ISO 3166 country code enabling local storage.
+      attr_accessor :data_localization_region
+
+      validate :validate_pin
+      validates :data_localization_region, inclusion: { in: DataLocalizationRegions::ALL }, allow_nil: true
+
+      # @param pin [String, Integer] The 6-digit two-step verification PIN. If
+      #   two-step verification is already enabled on the number, this must be the
+      #   existing PIN.
+      # @param data_localization_region [String, Symbol, nil] One of
+      #   {DataLocalizationRegions::ALL}, either casing.
+      # @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(pin:, data_localization_region: nil)
+        @pin = pin
+        @data_localization_region = DataLocalizationRegions.normalize(data_localization_region)
+
+        validate!
+      end
+
+      # @return [Hash] The registration payload.
+      def serialize
+        { messaging_product: Defaults::MESSAGING_PRODUCT, pin: pin.to_s, data_localization_region: }.compact
+      end
+
+      # Redacts the pin so it never leaks into logs or console output.
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} pin=[REDACTED] data_localization_region=#{data_localization_region.inspect}>"
+      end
+
+      class << self
+        # @param pin [String, Integer] See {#initialize}.
+        # @param client [Whatsapp::Client] The WhatsApp client instance.
+        # @param data_localization_region [String, Symbol, nil] See {#initialize}.
+        # @return [Response]
+        # @raise [ActiveModel::ValidationError] if the pin or region is invalid.
+        # @raise [Error] if no phone number ID is configured, or the request fails.
+        def call(pin:, client: Client.new, data_localization_region: nil)
+          body = new(pin:, data_localization_region:).serialize
+          response = client.connection.post(edge_path(client, Defaults::EDGE), json: body)
+
+          Response.deserialize(
+            parse_json(handle_response!(response, error_class: Error, action: "register business phone number"))
+          )
+        end
+      end
+
+    private
+
+      # @return [void]
+      def validate_pin
+        errors.add(:pin, "must be exactly 6 digits") unless pin.to_s.match?(Defaults::PIN_PATTERN)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    # Requests a verification code (by SMS or voice call) for a business phone number —
+    # the first step of the onboarding flow this module wraps end to end:
+    # `RequestCode` -> {VerifyCode} -> {Register}.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/phone-number-verification-request-code-api
+    class RequestCode
+      include ActiveModel::Validations
+      extend ResponseHandling
+      extend Transport
+
+      module Defaults
+        EDGE = "request_code"
+      end
+
+      # How Meta delivers the verification code.
+      module CodeMethods
+        SMS = "SMS"
+        VOICE = "VOICE"
+
+        ALL = [SMS, VOICE].freeze
+
+        # Normalizes caller input to a canonical uppercase code method.
+        # Unrecognized values are returned as a string (preserving the original
+        # casing) so the inclusion validator can reject them.
+        # @param value [String, Symbol, nil]
+        # @return [String, nil]
+        def self.normalize(value)
+          return if value.nil?
+
+          candidate = value.to_s.upcase
+          ALL.include?(candidate) ? candidate : value.to_s
+        end
+      end
+
+      # @!attribute [rw] code_method
+      #   @return [String] One of {CodeMethods::ALL}.
+      attr_accessor :code_method
+
+      # @!attribute [rw] language
+      #   @return [String] The locale for the verification message (e.g. `"en_US"`).
+      attr_accessor :language
+
+      validates :code_method, presence: true, inclusion: { in: CodeMethods::ALL }
+      validates :language, presence: true
+
+      # @param code_method [String, Symbol] One of {CodeMethods::ALL}, either casing.
+      # @param language [String] The locale for the verification message. Meta
+      #   publishes no enum for this field, so only presence is checked — unlike
+      #   {Register}'s `pin`, which has a documented format.
+      # @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(code_method:, language:)
+        @code_method = CodeMethods.normalize(code_method)
+        @language = language
+
+        validate!
+      end
+
+      # @return [Hash] The request-code payload. Both fields are documented required,
+      #   so neither is ever compacted away.
+      def serialize
+        { code_method:, language: }
+      end
+
+      class << self
+        # @param code_method [String, Symbol] See {#initialize}.
+        # @param language [String] See {#initialize}.
+        # @param client [Whatsapp::Client] The WhatsApp client instance.
+        # @return [Response]
+        # @raise [ActiveModel::ValidationError] if the code method or language is invalid.
+        # @raise [Error] if no phone number ID is configured, or the request fails.
+        def call(code_method:, language:, client: Client.new)
+          body = new(code_method:, language:).serialize
+          response = client.connection.post(edge_path(client, Defaults::EDGE), json: body)
+
+          Response.deserialize(
+            parse_json(handle_response!(response, error_class: Error, action: "request verification code"))
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    # 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}, {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
+      #   @return [Boolean] Whether the action succeeded.
+      attr_accessor :success
+
+      # @!attribute [rw] id
+      #   @return [String, nil] The phone number ID, only ever present on
+      #     {VerifyCode}'s response.
+      attr_accessor :id
+
+      # @param success [Boolean]
+      # @param id [String, nil]
+      def initialize(success: false, id: nil)
+        @success = success
+        @id = id
+      end
+
+      class << self
+        # @param response [Hash, nil] The parsed response body.
+        # @return [Response]
+        def deserialize(response)
+          response ||= {}
+
+          new(success: response["success"] == true, id: response["id"])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    # 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", "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)
+        scoped_path(client, :phone_id, action, error_class: Error, purpose: "the #{action} edge")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    # Confirms the verification code sent by {RequestCode}, the second step of the
+    # onboarding flow this module wraps end to end: {RequestCode} -> `VerifyCode` ->
+    # {Register}.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/verify-code-api
+    class VerifyCode
+      include ActiveModel::Validations
+      extend ResponseHandling
+      extend Transport
+
+      module Defaults
+        EDGE = "verify_code"
+      end
+
+      # @!attribute [rw] code
+      #   @return [String] The verification code received via SMS or voice call.
+      attr_accessor :code
+
+      validates :code, presence: true
+
+      # @param code [String, Integer] The verification code received via SMS or voice
+      #   call. Meta documents this as a plain string with no format rule, unlike
+      #   {Register}'s `pin`, so only presence is checked.
+      # @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(code:)
+        @code = code
+
+        validate!
+      end
+
+      # @return [Hash] The verify-code payload.
+      def serialize
+        { code: code.to_s }
+      end
+
+      # Redacts the code so it never leaks into logs or console output, same as
+      # {Register#inspect} redacts the pin.
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} code=[REDACTED]>"
+      end
+
+      class << self
+        # @param code [String, Integer] See {#initialize}.
+        # @param client [Whatsapp::Client] The WhatsApp client instance.
+        # @return [Response]
+        # @raise [ActiveModel::ValidationError] if the code is blank.
+        # @raise [Error] if no phone number ID is configured, or the request fails.
+        def call(code:, client: Client.new)
+          body = new(code:).serialize
+          response = client.connection.post(edge_path(client, Defaults::EDGE), json: body)
+
+          Response.deserialize(
+            parse_json(handle_response!(response, error_class: Error, action: "verify code"))
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  # Onboards and deboards a business phone number with Cloud API: requesting and
+  # verifying a phone number's verification code, then registering or deregistering it.
+  #
+  # This is the switch that makes a phone number usable — or not — with Cloud API in
+  # 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. 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.
+  #
+  # {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
+  end
+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/list.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    # Lists the apps currently subscribed to a WABA's webhook notifications.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/subscribed-apps-api
+    class List
+      extend ResponseHandling
+      extend Transport
+
+      class << self
+        # @param client [Whatsapp::Client] The WhatsApp client instance.
+        # @param fields [Array<String>, String, nil] Restrict each app to these fields
+        #   (`id`, `name`, `link`).
+        # @return [Response::Collection]
+        # @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(edge_path(client), params:)
+
+          Response::Collection.deserialize(
+            parse_json(handle_response!(response, error_class: Error, action: "list subscribed apps"))
+          )
+        end
+      end
+    end
+  end
+end