ruby-whatsapp 0.3.0

data/lib/ruby/whatsapp/webhook/messages.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # The `messages` webhook field's `value` payload — the only field with a
+    # confirmed, JSON-example-backed schema in Meta's docs. Carries inbound
+    # messages and/or delivery status updates for one of your business phone numbers.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+    class Messages
+      # @!attribute [rw] messaging_product
+      #   @return [String, nil]
+      attr_accessor :messaging_product
+
+      # @!attribute [rw] metadata
+      #   @return [Metadata, nil]
+      attr_accessor :metadata
+
+      # @!attribute [rw] contacts
+      #   @return [Array<Contact>]
+      attr_accessor :contacts
+
+      # @!attribute [rw] messages
+      #   @return [Array<Message::Base>]
+      attr_accessor :messages
+
+      # @!attribute [rw] statuses
+      #   @return [Array<Status>]
+      attr_accessor :statuses
+
+      def initialize(messaging_product:, metadata:, contacts:, messages:, statuses:)
+        @messaging_product = messaging_product
+        @metadata = metadata
+        @contacts = contacts
+        @messages = messages
+        @statuses = statuses
+      end
+
+      class << self
+        # @param data [Hash] The raw `messages` field's `value` hash.
+        # @return [Messages]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            messaging_product: data["messaging_product"],
+            metadata: data["metadata"] ? Metadata.deserialize(data["metadata"]) : nil,
+            contacts: Array(data["contacts"]).map { |contact_data| Contact.deserialize(contact_data) },
+            messages: Array(data["messages"]).map { |message_data| Message.deserialize(message_data) },
+            statuses: Array(data["statuses"]).map { |status_data| Status.deserialize(status_data) }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/metadata.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # The `metadata` object present on most webhook `value` payloads, identifying
+    # which of your business phone numbers the notification is about.
+    class Metadata
+      # @!attribute [rw] display_phone_number
+      #   @return [String, nil]
+      attr_accessor :display_phone_number
+
+      # @!attribute [rw] phone_number_id
+      #   @return [String, nil]
+      attr_accessor :phone_number_id
+
+      def initialize(display_phone_number:, phone_number_id:)
+        @display_phone_number = display_phone_number
+        @phone_number_id = phone_number_id
+      end
+
+      class << self
+        # @param data [Hash] The raw `metadata` hash.
+        # @return [Metadata]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            display_phone_number: data["display_phone_number"],
+            phone_number_id: data["phone_number_id"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/notification.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Top-level deserialization entry point for an incoming webhook POST body.
+    # @example
+    #   Whatsapp::Webhook::Notification.deserialize(JSON.parse(request.body.read))
+    class Notification
+      # @!attribute [rw] object
+      #   @return [String]
+      attr_accessor :object
+
+      # @!attribute [rw] entry
+      #   @return [Array<Entry>]
+      attr_accessor :entry
+
+      def initialize(object:, entry:)
+        @object = object
+        @entry = entry
+      end
+
+      class << self
+        # @param data [Hash] The parsed JSON request body.
+        # @return [Notification]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            object: data["object"],
+            entry: Array(data["entry"]).map { |entry_data| Entry.deserialize(entry_data) }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/partner_solutions.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Multi-Partner Solution status changes.
+    #
+    # Best-effort schema: Meta's public docs describe this field in one line with
+    # no published JSON example. Validate against a real payload (App Dashboard
+    # "send test payload") before relying on these attribute names in production.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+    class PartnerSolutions
+      # @!attribute [rw] solution_id
+      #   @return [String, nil]
+      attr_accessor :solution_id
+
+      # @!attribute [rw] event
+      #   @return [String, nil]
+      attr_accessor :event
+
+      def initialize(solution_id:, event:)
+        @solution_id = solution_id
+        @event = event
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [PartnerSolutions]
+        def deserialize(data)
+          data ||= {}
+
+          new(solution_id: data["solution_id"], event: data["event"])
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/payment_configuration_update.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Payment configuration changes (India/Brazil).
+    #
+    # Best-effort schema: Meta's public docs describe this field in one line with
+    # no published JSON example. Validate against a real payload (App Dashboard
+    # "send test payload") before relying on these attribute names in production.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+    class PaymentConfigurationUpdate
+      # @!attribute [rw] configuration_name
+      #   @return [String, nil]
+      attr_accessor :configuration_name
+
+      # @!attribute [rw] provider_name
+      #   @return [String, nil]
+      attr_accessor :provider_name
+
+      # @!attribute [rw] provider_mid
+      #   @return [String, nil]
+      attr_accessor :provider_mid
+
+      # @!attribute [rw] status
+      #   @return [String, nil]
+      attr_accessor :status
+
+      def initialize(configuration_name:, provider_name:, provider_mid:, status:)
+        @configuration_name = configuration_name
+        @provider_name = provider_name
+        @provider_mid = provider_mid
+        @status = status
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [PaymentConfigurationUpdate]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            configuration_name: data["configuration_name"],
+            provider_name: data["provider_name"],
+            provider_mid: data["provider_mid"],
+            status: data["status"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/phone_number_name_update.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Display name verification outcomes for a business phone number.
+    #
+    # Best-effort schema: Meta's public docs describe this field in one line with
+    # no published JSON example. Validate against a real payload (App Dashboard
+    # "send test payload") before relying on these attribute names in production.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+    class PhoneNumberNameUpdate
+      # @!attribute [rw] phone_number
+      #   @return [String, nil]
+      attr_accessor :phone_number
+
+      # @!attribute [rw] decision
+      #   @return [String, nil] e.g. `"APPROVED"`, `"REJECTED"`.
+      attr_accessor :decision
+
+      # @!attribute [rw] requested_verified_name
+      #   @return [String, nil]
+      attr_accessor :requested_verified_name
+
+      # @!attribute [rw] rejection_reason
+      #   @return [String, nil]
+      attr_accessor :rejection_reason
+
+      def initialize(phone_number:, decision:, requested_verified_name:, rejection_reason: nil)
+        @phone_number = phone_number
+        @decision = decision
+        @requested_verified_name = requested_verified_name
+        @rejection_reason = rejection_reason
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [PhoneNumberNameUpdate]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            phone_number: data["phone_number"],
+            decision: data["decision"],
+            requested_verified_name: data["requested_verified_name"],
+            rejection_reason: data["rejection_reason"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/phone_number_quality_update.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Business phone throughput/quality level changes.
+    #
+    # Best-effort schema: Meta's public docs describe this field in one line with
+    # no published JSON example. Validate against a real payload (App Dashboard
+    # "send test payload") before relying on these attribute names in production.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+    class PhoneNumberQualityUpdate
+      # @!attribute [rw] display_phone_number
+      #   @return [String, nil]
+      attr_accessor :display_phone_number
+
+      # @!attribute [rw] event
+      #   @return [String, nil] e.g. `"UPGRADE"`, `"DOWNGRADE"`.
+      attr_accessor :event
+
+      # @!attribute [rw] current_limit
+      #   @return [String, nil] e.g. `"TIER_50"`, `"TIER_250"`, `"TIER_1K"`.
+      attr_accessor :current_limit
+
+      def initialize(display_phone_number:, event:, current_limit:)
+        @display_phone_number = display_phone_number
+        @event = event
+        @current_limit = current_limit
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [PhoneNumberQualityUpdate]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            display_phone_number: data["display_phone_number"],
+            event: data["event"],
+            current_limit: data["current_limit"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/security.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Phone number security settings modifications (e.g. two-step verification changes).
+    #
+    # Best-effort schema: Meta's public docs describe this field in one line with
+    # no published JSON example. Validate against a real payload (App Dashboard
+    # "send test payload") before relying on these attribute names in production.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+    class Security
+      # @!attribute [rw] display_phone_number
+      #   @return [String, nil]
+      attr_accessor :display_phone_number
+
+      # @!attribute [rw] event
+      #   @return [String, nil]
+      attr_accessor :event
+
+      # @!attribute [rw] requester
+      #   @return [String, nil]
+      attr_accessor :requester
+
+      def initialize(display_phone_number:, event:, requester: nil)
+        @display_phone_number = display_phone_number
+        @event = event
+        @requester = requester
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [Security]
+        def deserialize(data)
+          data ||= {}
+
+          new(display_phone_number: data["display_phone_number"], event: data["event"], requester: data["requester"])
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/signature.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Verifies the `X-Hub-Signature-256` header Meta attaches to every webhook POST,
+    # an HMAC-SHA256 of the raw request body keyed by the app secret.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+    class Signature
+      PREFIX = "sha256="
+
+      class << self
+        # @param payload [String] The raw (unparsed) request body.
+        # @param header [String, nil] The `X-Hub-Signature-256` header value.
+        # @param app_secret [String, nil] The secret to verify against. Defaults to the
+        #   globally configured secret; pass an explicit value for multi-tenant apps where
+        #   each account has its own Meta App (and therefore its own secret).
+        # @return [Boolean] Whether the header matches the computed signature.
+        def valid?(payload:, header:, app_secret: Whatsapp.configuration.app_secret)
+          return false if header.nil? || header.empty?
+          return false if app_secret.nil? || app_secret.empty?
+
+          expected = PREFIX + OpenSSL::HMAC.hexdigest("SHA256", app_secret, payload)
+          ActiveSupport::SecurityUtils.secure_compare(expected, header)
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/smb_app_state_sync/state_sync.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class SmbAppStateSync
+      # A single contact-sync entry within an `smb_app_state_sync` notification.
+      class StateSync
+        # @!attribute [rw] type
+        #   @return [String, nil]
+        attr_accessor :type
+
+        # @!attribute [rw] action
+        #   @return [String, nil] e.g. `"add"`, `"remove"`, `"update"`.
+        attr_accessor :action
+
+        # @!attribute [rw] contact
+        #   @return [Hash] Left untyped — Meta's docs don't publish this entry's schema.
+        attr_accessor :contact
+
+        def initialize(type:, action:, contact:)
+          @type = type
+          @action = action
+          @contact = contact
+        end
+
+        class << self
+          # @param data [Hash] A raw `state_sync[]` entry.
+          # @return [StateSync]
+          def deserialize(data)
+            data ||= {}
+
+            new(type: data["type"], action: data["action"], contact: data["contact"] || {})
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/smb_app_state_sync.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Contact synchronization for onboarded WhatsApp Business app users.
+    #
+    # Best-effort schema: Meta's public docs describe this field in one line with
+    # no published JSON example; each entry's `contact` shape isn't confidently
+    # typeable from that description alone, so it's kept as a raw hash rather
+    # than guessing further. Validate against a real payload before relying on
+    # this in production.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+    class SmbAppStateSync
+      # @!attribute [rw] state_sync
+      #   @return [Array<StateSync>]
+      attr_accessor :state_sync
+
+      def initialize(state_sync:)
+        @state_sync = state_sync
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [SmbAppStateSync]
+        def deserialize(data)
+          data ||= {}
+
+          new(state_sync: Array(data["state_sync"]).map { |entry| StateSync.deserialize(entry) })
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/smb_message_echoes.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Messages sent via the WhatsApp Business App or a linked device, echoed back
+    # so a Cloud API integration stays in sync with what the business itself sent.
+    #
+    # Best-effort schema: Meta's public docs describe this field in one line with
+    # no published JSON example, but do state these mirror the standard inbound
+    # `messages` shape — hence reusing {Message.deserialize} here. The exact key
+    # name (`message_echoes`) is a best-effort guess; validate against a real
+    # payload before relying on it in production.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+    class SmbMessageEchoes
+      # @!attribute [rw] messaging_product
+      #   @return [String, nil]
+      attr_accessor :messaging_product
+
+      # @!attribute [rw] metadata
+      #   @return [Metadata, nil]
+      attr_accessor :metadata
+
+      # @!attribute [rw] message_echoes
+      #   @return [Array<Message::Base>]
+      attr_accessor :message_echoes
+
+      def initialize(messaging_product:, metadata:, message_echoes:)
+        @messaging_product = messaging_product
+        @metadata = metadata
+        @message_echoes = message_echoes
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [SmbMessageEchoes]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            messaging_product: data["messaging_product"],
+            metadata: data["metadata"] ? Metadata.deserialize(data["metadata"]) : nil,
+            message_echoes: Array(data["message_echoes"]).map { |echo_data| Message.deserialize(echo_data) }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/status/conversation.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Status
+      # The conversation window a status update was billed/attributed to.
+      class Conversation
+        # @!attribute [rw] id
+        #   @return [String, nil]
+        attr_accessor :id
+
+        # @!attribute [rw] origin_type
+        #   @return [String, nil] e.g. `"service"`, `"marketing"`, `"utility"`, `"authentication"`.
+        attr_accessor :origin_type
+
+        # @!attribute [rw] expiration_timestamp
+        #   @return [String, nil]
+        attr_accessor :expiration_timestamp
+
+        def initialize(id:, origin_type:, expiration_timestamp: nil)
+          @id = id
+          @origin_type = origin_type
+          @expiration_timestamp = expiration_timestamp
+        end
+
+        class << self
+          # @param data [Hash] The raw `conversation` hash.
+          # @return [Conversation]
+          def deserialize(data)
+            data ||= {}
+
+            new(
+              id: data["id"],
+              origin_type: data.dig("origin", "type"),
+              expiration_timestamp: data["expiration_timestamp"]
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/status/pricing.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Status
+      # The billing details attached to a status update.
+      class Pricing
+        # @!attribute [rw] billable
+        #   @return [Boolean, nil]
+        attr_accessor :billable
+
+        # @!attribute [rw] pricing_model
+        #   @return [String, nil]
+        attr_accessor :pricing_model
+
+        # @!attribute [rw] category
+        #   @return [String, nil] e.g. `"service"`, `"marketing"`, `"utility"`, `"authentication"`.
+        attr_accessor :category
+
+        def initialize(billable:, pricing_model:, category:)
+          @billable = billable
+          @pricing_model = pricing_model
+          @category = category
+        end
+
+        class << self
+          # @param data [Hash] The raw `pricing` hash.
+          # @return [Pricing]
+          def deserialize(data)
+            data ||= {}
+
+            new(billable: data["billable"], pricing_model: data["pricing_model"], category: data["category"])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/status.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # A single `statuses[]` entry from the `messages` webhook field — a delivery
+    # status update (sent/delivered/read/failed) for a message you sent.
+    class Status
+      # @!attribute [rw] id
+      #   @return [String, nil] The wamid of the message this status is about.
+      attr_accessor :id
+
+      # @!attribute [rw] status
+      #   @return [String, nil] `"sent"`, `"delivered"`, `"read"`, or `"failed"`.
+      attr_accessor :status
+
+      # @!attribute [rw] timestamp
+      #   @return [String, nil]
+      attr_accessor :timestamp
+
+      # @!attribute [rw] recipient_id
+      #   @return [String, nil]
+      attr_accessor :recipient_id
+
+      # @!attribute [rw] conversation
+      #   @return [Conversation, nil]
+      attr_accessor :conversation
+
+      # @!attribute [rw] pricing
+      #   @return [Pricing, nil]
+      attr_accessor :pricing
+
+      # @!attribute [rw] errors
+      #   @return [Array<Error>]
+      attr_accessor :errors
+
+      def initialize(id:, status:, timestamp:, recipient_id:, conversation: nil, pricing: nil, errors: [])
+        @id = id
+        @status = status
+        @timestamp = timestamp
+        @recipient_id = recipient_id
+        @conversation = conversation
+        @pricing = pricing
+        @errors = errors
+      end
+
+      class << self
+        # @param data [Hash] A raw `statuses[]` entry.
+        # @return [Status]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            id: data["id"],
+            status: data["status"],
+            timestamp: data["timestamp"],
+            recipient_id: data["recipient_id"],
+            conversation: data["conversation"] ? Conversation.deserialize(data["conversation"]) : nil,
+            pricing: data["pricing"] ? Pricing.deserialize(data["pricing"]) : nil,
+            errors: Array(data["errors"]).map { |error_data| Error.deserialize(error_data) }
+          )
+        end
+      end
+    end
+  end
+end