ruby-whatsapp 0.3.1 → 0.4.2

data/lib/ruby/whatsapp/subscribed_app/response/app.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    module Response
+      # One app subscribed to a WABA's webhook notifications.
+      #
+      # Meta nests `id`/`name`/`link` inside `whatsapp_business_api_data`; this class
+      # flattens that away since the wrapper carries no information of its own.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/subscribed-apps-api
+      class App
+        # @!attribute [rw] id
+        #   @return [String, nil] The subscribed app's ID.
+        attr_accessor :id
+
+        # @!attribute [rw] name
+        #   @return [String, nil] The subscribed app's name.
+        attr_accessor :name
+
+        # @!attribute [rw] link
+        #   @return [String, nil] A link to the app.
+        attr_accessor :link
+
+        # @!attribute [rw] override_callback_uri
+        #   @return [String, nil] The per-WABA webhook callback override, if one is set.
+        attr_accessor :override_callback_uri
+
+        # @param id [String, nil]
+        # @param name [String, nil]
+        # @param link [String, nil]
+        # @param override_callback_uri [String, nil]
+        def initialize(id: nil, name: nil, link: nil, override_callback_uri: nil)
+          @id = id
+          @name = name
+          @link = link
+          @override_callback_uri = override_callback_uri
+        end
+
+        class << self
+          # @param data [Hash, nil] One element of the `data` array.
+          # @return [App]
+          def deserialize(data)
+            data ||= {}
+            api_data = data["whatsapp_business_api_data"] || {}
+
+            new(
+              id: api_data["id"],
+              name: api_data["name"],
+              link: api_data["link"],
+              override_callback_uri: data["override_callback_uri"]
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    module Response
+      # The apps currently subscribed to a WABA's webhook notifications: `{data}`.
+      #
+      # Enumerable over its apps, so `list.map(&:name)` reads naturally without
+      # reaching for `.data` first.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/subscribed-apps-api
+      class Collection
+        include Enumerable
+
+        # @!attribute [rw] data
+        #   @return [Array<App>]
+        attr_accessor :data
+
+        # @param data [Array<App>]
+        def initialize(data: [])
+          @data = data
+        end
+
+        class << self
+          # @param response [Hash, nil] The parsed response body.
+          # @return [Collection]
+          def deserialize(response)
+            response ||= {}
+
+            new(data: Array(response["data"]).map { |entry| App.deserialize(entry) })
+          end
+        end
+
+        # @yieldparam app [App]
+        # @return [Enumerator]
+        def each(&)
+          data.each(&)
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/subscribed_app/response/subscription.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    module Response
+      # The response to subscribing this app to a WABA's webhook notifications:
+      # `{success, data}`.
+      #
+      # `data` mirrors {Collection}'s shape exactly, since Meta echoes back every app
+      # now subscribed — deserialization is delegated to {Collection.deserialize}
+      # rather than duplicating the `App` mapping.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/subscribed-apps-api
+      class Subscription
+        include Enumerable
+
+        # @!attribute [rw] success
+        #   @return [Boolean] Whether the subscription succeeded.
+        attr_accessor :success
+
+        # @!attribute [rw] data
+        #   @return [Array<App>]
+        attr_accessor :data
+
+        # @param success [Boolean]
+        # @param data [Array<App>]
+        def initialize(success: false, data: [])
+          @success = success
+          @data = data
+        end
+
+        class << self
+          # @param response [Hash, nil] The parsed response body.
+          # @return [Subscription]
+          def deserialize(response)
+            response ||= {}
+
+            new(success: response["success"] == true, data: Collection.deserialize(response).to_a)
+          end
+        end
+
+        # @yieldparam app [App]
+        # @return [Enumerator]
+        def each(&)
+          data.each(&)
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/subscribed_app/response/unsubscription.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    module Response
+      # The response to unsubscribing this app from a WABA's webhook notifications:
+      # `{success}`.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/subscribed-apps-api
+      class Unsubscription
+        # @!attribute [rw] success
+        #   @return [Boolean] Whether the app was unsubscribed.
+        attr_accessor :success
+
+        # @param success [Boolean]
+        def initialize(success: false)
+          @success = success
+        end
+
+        class << self
+          # @param response [Hash, nil] The parsed response body.
+          # @return [Unsubscription]
+          def deserialize(response)
+            response ||= {}
+
+            new(success: response["success"] == true)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    # Deserializers for the responses of the `subscribed_apps` edge.
+    #
+    # Three response shapes, one per action, so a namespace of small classes rather
+    # than a single one with optional fields:
+    #
+    #   {Collection}     `{data}`            List
+    #   {Subscription}   `{success, data}`   Subscribe
+    #   {Unsubscription} `{success}`         Unsubscribe
+    #
+    # Every class follows the gem's `.deserialize(data)` convention and tolerates a nil
+    # or partial payload, so a field Meta stops sending cannot raise.
+    module Response
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    # Subscribes this app to a WABA's webhook notifications.
+    #
+    # `override_callback_uri`/`verify_token` are for Tech Providers routing several
+    # WABAs' notifications to different callback URLs instead of the one configured on
+    # the app itself.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/subscribed-apps-api
+    class Subscribe
+      extend ResponseHandling
+      extend Transport
+
+      class << self
+        # @param client [Whatsapp::Client] The WhatsApp client instance.
+        # @param override_callback_uri [String, nil] A per-WABA webhook callback override.
+        # @param verify_token [String, nil] The token Meta echoes back if it re-verifies
+        #   `override_callback_uri`.
+        # @return [Response::Subscription]
+        # @raise [Error] if no WABA ID is configured, or the request fails.
+        def call(client: Client.new, override_callback_uri: nil, verify_token: nil)
+          body = { override_callback_uri:, verify_token: }.compact
+          response = client.connection.post(edge_path(client), json: body)
+
+          Response::Subscription.deserialize(
+            parse_json(handle_response!(response, error_class: Error, action: "subscribe app"))
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    # 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)
+        scoped_path(client, :waba_id, "subscribed_apps", error_class: Error, purpose: "subscribed apps")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    # Unsubscribes this app from a WABA's webhook notifications. All webhook
+    # deliveries for that WABA stop immediately.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/subscribed-apps-api
+    class Unsubscribe
+      extend ResponseHandling
+      extend Transport
+
+      class << self
+        # @param client [Whatsapp::Client] The WhatsApp client instance.
+        # @return [Response::Unsubscription]
+        # @raise [Error] if no WABA ID is configured, or the request fails.
+        def call(client: Client.new)
+          response = client.connection.delete(edge_path(client))
+
+          Response::Unsubscription.deserialize(
+            parse_json(handle_response!(response, error_class: Error, action: "unsubscribe app"))
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/subscribed_app.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  # Subscribes or unsubscribes this app from a WhatsApp Business Account's webhook
+  # notifications, and lists which apps are currently subscribed.
+  #
+  # This is what turns webhook delivery on and off in the first place — the opposite
+  # concern from {Whatsapp::Webhook}, which only deserializes notifications once Meta
+  # is already sending them. Addresses `waba_id`, not `phone_id`, like
+  # {Whatsapp::MessageTemplates}. See `lib/ruby/whatsapp/subscribed_app/CLAUDE.md`.
+  # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/subscribed-apps-api
+  module SubscribedApp
+    class Error < Whatsapp::Error; end
+  end
+end

data/lib/ruby/whatsapp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-whatsapp
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Raniery
@@ -82,7 +82,75 @@ 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
+- lib/ruby/whatsapp/business_phone_number/transport.rb
+- lib/ruby/whatsapp/business_phone_number/verify_code.rb
 - lib/ruby/whatsapp/client.rb
 - lib/ruby/whatsapp/configuration.rb
 - lib/ruby/whatsapp/instrumentation.rb
@@ -168,9 +236,20 @@ 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
+- lib/ruby/whatsapp/subscribed_app.rb
+- lib/ruby/whatsapp/subscribed_app/list.rb
+- lib/ruby/whatsapp/subscribed_app/response.rb
+- lib/ruby/whatsapp/subscribed_app/response/app.rb
+- lib/ruby/whatsapp/subscribed_app/response/collection.rb
+- lib/ruby/whatsapp/subscribed_app/response/subscription.rb
+- lib/ruby/whatsapp/subscribed_app/response/unsubscription.rb
+- lib/ruby/whatsapp/subscribed_app/subscribe.rb
+- lib/ruby/whatsapp/subscribed_app/transport.rb
+- lib/ruby/whatsapp/subscribed_app/unsubscribe.rb
 - lib/ruby/whatsapp/utils/language_codes.rb
 - lib/ruby/whatsapp/version.rb
 - lib/ruby/whatsapp/webhook.rb