ruby-whatsapp 0.3.0

data/lib/ruby/whatsapp/webhook/message/media.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # Shared shape for the media-backed message types (image, video, audio,
+      # document, sticker) — a media asset id you can resolve via {Whatsapp::Media},
+      # plus its mime type and content hash.
+      class Media < Base
+        # @!attribute [rw] media_id
+        #   @return [String, nil] The media asset id (resolve via {Whatsapp::Media#url}).
+        attr_accessor :media_id
+
+        # @!attribute [rw] mime_type
+        #   @return [String, nil]
+        attr_accessor :mime_type
+
+        # @!attribute [rw] sha256
+        #   @return [String, nil]
+        attr_accessor :sha256
+
+        # @!attribute [rw] caption
+        #   @return [String, nil]
+        attr_accessor :caption
+
+        def initialize(media_id:, mime_type:, sha256:, caption: nil, **base_attributes)
+          super(**base_attributes)
+
+          @media_id = media_id
+          @mime_type = mime_type
+          @sha256 = sha256
+          @caption = caption
+        end
+
+        class << self
+          # Extracts the media-specific fields nested under the given key
+          # (e.g. `"image"`, `"video"`), for subclasses to merge with their own
+          # extra attributes before calling `new`.
+          # @param data [Hash] The raw message hash.
+          # @param key [String] The type-specific nested key (e.g. `"image"`).
+          # @return [Hash]
+          def media_attributes(data, key)
+            {
+              media_id: data.dig(key, "id"),
+              mime_type: data.dig(key, "mime_type"),
+              sha256: data.dig(key, "sha256"),
+              caption: data.dig(key, "caption"),
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/message/order/product_item.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      class Order < Base
+        # A single line item within an inbound order message.
+        class ProductItem
+          # @!attribute [rw] product_retailer_id
+          #   @return [String, nil] The catalog SKU.
+          attr_accessor :product_retailer_id
+
+          # @!attribute [rw] quantity
+          #   @return [Integer, nil]
+          attr_accessor :quantity
+
+          # @!attribute [rw] item_price
+          #   @return [Float, nil]
+          attr_accessor :item_price
+
+          # @!attribute [rw] currency
+          #   @return [String, nil]
+          attr_accessor :currency
+
+          def initialize(product_retailer_id:, quantity:, item_price:, currency:)
+            @product_retailer_id = product_retailer_id
+            @quantity = quantity
+            @item_price = item_price
+            @currency = currency
+          end
+
+          class << self
+            # @param data [Hash] A raw `product_items[]` entry.
+            # @return [ProductItem]
+            def deserialize(data)
+              data ||= {}
+
+              new(
+                product_retailer_id: data["product_retailer_id"],
+                quantity: data["quantity"],
+                item_price: data["item_price"],
+                currency: data["currency"]
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/message/order.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # An inbound order placed against a Meta catalog.
+      class Order < Base
+        # @!attribute [rw] catalog_id
+        #   @return [String, nil]
+        attr_accessor :catalog_id
+
+        # @!attribute [rw] text
+        #   @return [String, nil] Optional note the customer attached to the order.
+        attr_accessor :text
+
+        # @!attribute [rw] product_items
+        #   @return [Array<ProductItem>]
+        attr_accessor :product_items
+
+        def initialize(catalog_id:, product_items:, text: nil, **base_attributes)
+          super(**base_attributes)
+
+          @catalog_id = catalog_id
+          @text = text
+          @product_items = product_items
+        end
+
+        class << self
+          # @param data [Hash] The raw message hash.
+          # @return [Order]
+          def deserialize(data)
+            new(
+              catalog_id: data.dig("order", "catalog_id"),
+              text: data.dig("order", "text"),
+              product_items: Array(data.dig("order", "product_items")).map { |item| ProductItem.deserialize(item) },
+              **common_attributes(data)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/message/reaction.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # An inbound emoji reaction to a previous message.
+      class Reaction < Base
+        # @!attribute [rw] message_id
+        #   @return [String, nil] The wamid of the message being reacted to.
+        attr_accessor :message_id
+
+        # @!attribute [rw] emoji
+        #   @return [String, nil] Empty when the user removed a previous reaction.
+        attr_accessor :emoji
+
+        def initialize(message_id:, emoji:, **base_attributes)
+          super(**base_attributes)
+
+          @message_id = message_id
+          @emoji = emoji
+        end
+
+        class << self
+          # @param data [Hash] The raw message hash.
+          # @return [Reaction]
+          def deserialize(data)
+            new(
+              message_id: data.dig("reaction", "message_id"),
+              emoji: data.dig("reaction", "emoji"),
+              **common_attributes(data)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/message/referral.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # Present when an inbound message originated from a Click-to-WhatsApp ad or a
+      # post/story with an embedded WhatsApp link.
+      class Referral
+        # @!attribute [rw] source_url
+        #   @return [String, nil]
+        attr_accessor :source_url
+
+        # @!attribute [rw] source_type
+        #   @return [String, nil]
+        attr_accessor :source_type
+
+        # @!attribute [rw] source_id
+        #   @return [String, nil]
+        attr_accessor :source_id
+
+        # @!attribute [rw] headline
+        #   @return [String, nil]
+        attr_accessor :headline
+
+        # @!attribute [rw] body
+        #   @return [String, nil]
+        attr_accessor :body
+
+        # @!attribute [rw] media_type
+        #   @return [String, nil]
+        attr_accessor :media_type
+
+        # @!attribute [rw] image_url
+        #   @return [String, nil]
+        attr_accessor :image_url
+
+        # @!attribute [rw] video_url
+        #   @return [String, nil]
+        attr_accessor :video_url
+
+        # @!attribute [rw] thumbnail_url
+        #   @return [String, nil]
+        attr_accessor :thumbnail_url
+
+        def initialize(source_url:, source_type:, source_id:, headline:, body:, media_type:, image_url: nil,
+          video_url: nil, thumbnail_url: nil)
+          @source_url = source_url
+          @source_type = source_type
+          @source_id = source_id
+          @headline = headline
+          @body = body
+          @media_type = media_type
+          @image_url = image_url
+          @video_url = video_url
+          @thumbnail_url = thumbnail_url
+        end
+
+        class << self
+          # @param data [Hash, nil] The raw `referral` hash.
+          # @return [Referral, nil]
+          def deserialize(data)
+            return if data.nil?
+
+            new(
+              source_url: data["source_url"],
+              source_type: data["source_type"],
+              source_id: data["source_id"],
+              headline: data["headline"],
+              body: data["body"],
+              media_type: data["media_type"],
+              image_url: data["image_url"],
+              video_url: data["video_url"],
+              thumbnail_url: data["thumbnail_url"]
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/message/sticker.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # An inbound sticker message.
+      class Sticker < Media
+        # @!attribute [rw] animated
+        #   @return [Boolean, nil]
+        attr_accessor :animated
+
+        def initialize(animated: nil, **media_and_base_attributes)
+          super(**media_and_base_attributes)
+
+          @animated = animated
+        end
+
+        class << self
+          # @param data [Hash] The raw message hash.
+          # @return [Sticker]
+          def deserialize(data)
+            new(
+              animated: data.dig("sticker", "animated"),
+              **media_attributes(data, "sticker"),
+              **common_attributes(data)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/message/system.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # A system notice, e.g. that the customer changed their phone number.
+      class System < Base
+        # @!attribute [rw] body
+        #   @return [String, nil] Human-readable description of the change.
+        attr_accessor :body
+
+        # @!attribute [rw] identity
+        #   @return [String, nil]
+        attr_accessor :identity
+
+        # @!attribute [rw] wa_id
+        #   @return [String, nil] The customer's (possibly new) WhatsApp ID.
+        attr_accessor :wa_id
+
+        # @!attribute [rw] change_type
+        #   @return [String, nil] e.g. `"customer_changed_number"`, `"customer_identity_changed"`.
+        attr_accessor :change_type
+
+        def initialize(body:, identity:, wa_id:, change_type:, **base_attributes)
+          super(**base_attributes)
+
+          @body = body
+          @identity = identity
+          @wa_id = wa_id
+          @change_type = change_type
+        end
+
+        class << self
+          # @param data [Hash] The raw message hash.
+          # @return [System]
+          def deserialize(data)
+            new(
+              body: data.dig("system", "body"),
+              identity: data.dig("system", "identity"),
+              wa_id: data.dig("system", "wa_id"),
+              change_type: data.dig("system", "type"),
+              **common_attributes(data)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/message/text.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # An inbound plain-text message.
+      class Text < Base
+        # @!attribute [rw] body
+        #   @return [String, nil]
+        attr_accessor :body
+
+        def initialize(body:, **base_attributes)
+          super(**base_attributes)
+
+          @body = body
+        end
+
+        class << self
+          # @param data [Hash] The raw message hash.
+          # @return [Text]
+          def deserialize(data)
+            new(body: data.dig("text", "body"), **common_attributes(data))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/message/unknown.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # Fallback for a message `type` not in {Message::MESSAGE_TYPES} — either a
+      # type Meta added after this gem was released, or a message the Cloud API
+      # itself couldn't process (carries an `errors[]` array in that case).
+      class Unknown < Base
+        # @!attribute [rw] raw
+        #   @return [Hash] The full, untyped raw message hash.
+        attr_accessor :raw
+
+        # @!attribute [rw] errors
+        #   @return [Array<Error>]
+        attr_accessor :errors
+
+        def initialize(raw:, errors:, **base_attributes)
+          super(**base_attributes)
+
+          @raw = raw
+          @errors = errors
+        end
+
+        class << self
+          # @param data [Hash] The raw message hash.
+          # @return [Unknown]
+          def deserialize(data)
+            new(
+              raw: data,
+              errors: Array(data["errors"]).map { |error_data| Error.deserialize(error_data) },
+              **common_attributes(data)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/message/video.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # An inbound video message.
+      class Video < Media
+        class << self
+          # @param data [Hash] The raw message hash.
+          # @return [Video]
+          def deserialize(data)
+            new(**media_attributes(data, "video"), **common_attributes(data))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Dispatches a single `messages[]` entry from the `messages` webhook field to
+    # the class matching its `type`. Mirrors `Whatsapp::Messages::KINDS` — resolution
+    # goes through this frozen whitelist (never `const_get` on the `type` string,
+    # which comes straight from the internet), so an unrecognized type falls back to
+    # {Message::Unknown} rather than raising.
+    class Message
+      MESSAGE_TYPES = {
+        text: Text,
+        image: Image,
+        video: Video,
+        audio: Audio,
+        document: Document,
+        sticker: Sticker,
+        location: Location,
+        contacts: Contacts,
+        interactive: Interactive,
+        button: Button,
+        order: Order,
+        system: System,
+        reaction: Reaction,
+      }.freeze
+
+      class << self
+        # @param data [Hash] A raw `messages[]` entry.
+        # @return [Message::Base] One of the classes in {MESSAGE_TYPES}, or {Message::Unknown}.
+        def deserialize(data)
+          data ||= {}
+          klass = MESSAGE_TYPES.fetch(data["type"].to_s.to_sym) { Unknown }
+
+          klass.deserialize(data)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Template component modifications (e.g. Meta editing a template's header,
+    # body, or button on the business's behalf).
+    #
+    # 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 MessageTemplateComponentsUpdate
+      # @!attribute [rw] message_template_id
+      #   @return [Integer, nil]
+      attr_accessor :message_template_id
+
+      # @!attribute [rw] message_template_name
+      #   @return [String, nil]
+      attr_accessor :message_template_name
+
+      # @!attribute [rw] message_template_language
+      #   @return [String, nil]
+      attr_accessor :message_template_language
+
+      # @!attribute [rw] message_template_element
+      #   @return [String, nil] The component that changed, e.g. `"BODY"`.
+      attr_accessor :message_template_element
+
+      def initialize(message_template_id:, message_template_name:, message_template_language:,
+        message_template_element:)
+        @message_template_id = message_template_id
+        @message_template_name = message_template_name
+        @message_template_language = message_template_language
+        @message_template_element = message_template_element
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [MessageTemplateComponentsUpdate]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            message_template_id: data["message_template_id"],
+            message_template_name: data["message_template_name"],
+            message_template_language: data["message_template_language"],
+            message_template_element: data["message_template_element"]
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Template quality score changes (e.g. green/yellow/red rating shifts based
+    # on recipient feedback).
+    #
+    # 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 MessageTemplateQualityUpdate
+      # @!attribute [rw] message_template_id
+      #   @return [Integer, nil]
+      attr_accessor :message_template_id
+
+      # @!attribute [rw] message_template_name
+      #   @return [String, nil]
+      attr_accessor :message_template_name
+
+      # @!attribute [rw] message_template_language
+      #   @return [String, nil]
+      attr_accessor :message_template_language
+
+      # @!attribute [rw] previous_quality_score
+      #   @return [String, nil] e.g. `"GREEN"`, `"YELLOW"`, `"RED"`.
+      attr_accessor :previous_quality_score
+
+      # @!attribute [rw] new_quality_score
+      #   @return [String, nil]
+      attr_accessor :new_quality_score
+
+      def initialize(message_template_id:, message_template_name:, message_template_language:,
+        previous_quality_score:, new_quality_score:)
+        @message_template_id = message_template_id
+        @message_template_name = message_template_name
+        @message_template_language = message_template_language
+        @previous_quality_score = previous_quality_score
+        @new_quality_score = new_quality_score
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [MessageTemplateQualityUpdate]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            message_template_id: data["message_template_id"],
+            message_template_name: data["message_template_name"],
+            message_template_language: data["message_template_language"],
+            previous_quality_score: data["previous_quality_score"],
+            new_quality_score: data["new_quality_score"]
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Template status modifications — approved, rejected, flagged, paused, or
+    # disabled by Meta.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+    class MessageTemplateStatusUpdate
+      # @!attribute [rw] message_template_id
+      #   @return [Integer, nil]
+      attr_accessor :message_template_id
+
+      # @!attribute [rw] message_template_name
+      #   @return [String, nil]
+      attr_accessor :message_template_name
+
+      # @!attribute [rw] message_template_language
+      #   @return [String, nil]
+      attr_accessor :message_template_language
+
+      # @!attribute [rw] event
+      #   @return [String, nil] e.g. `"APPROVED"`, `"REJECTED"`, `"FLAGGED"`, `"PAUSED"`, `"DISABLED"`.
+      attr_accessor :event
+
+      # @!attribute [rw] reason
+      #   @return [String, nil]
+      attr_accessor :reason
+
+      def initialize(message_template_id:, message_template_name:, message_template_language:, event:, reason: nil)
+        @message_template_id = message_template_id
+        @message_template_name = message_template_name
+        @message_template_language = message_template_language
+        @event = event
+        @reason = reason
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [MessageTemplateStatusUpdate]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            message_template_id: data["message_template_id"],
+            message_template_name: data["message_template_name"],
+            message_template_language: data["message_template_language"],
+            event: data["event"],
+            reason: data["reason"]
+          )
+        end
+      end
+    end
+  end
+end