ruby-whatsapp 0.3.0

data/lib/ruby/whatsapp/utils/language_codes.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Utils
+    # Utility module for WhatsApp supported language codes
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/supported-languages
+    module LanguageCodes
+      CODES = %w[
+        af
+        sq
+        ar
+        az
+        bn
+        bg
+        ca
+        zh_CN
+        zh_HK
+        zh_TW
+        hr
+        cs
+        da
+        nl
+        en
+        en_GB
+        en_US
+        et
+        fil
+        fi
+        fr
+        ka
+        de
+        el
+        gu
+        ha
+        he
+        hi
+        hu
+        id
+        ga
+        it
+        ja
+        kn
+        kk
+        rw_RW
+        ko
+        ky_KG
+        lo
+        lv
+        lt
+        mk
+        ms
+        ml
+        mr
+        nb
+        fa
+        pl
+        pt_BR
+        pt_PT
+        pa
+        ro
+        ru
+        sr
+        sk
+        sl
+        es
+        es_AR
+        es_ES
+        es_MX
+        sw
+        sv
+        ta
+        te
+        th
+        tr
+        uk
+        ur
+        uz
+        vi
+        zu
+      ].freeze
+
+      # Check if a language code is valid
+      # @param code [String] The language code to validate
+      # @return [Boolean] true if the code is valid
+      def self.valid?(code)
+        CODES.include?(code.to_s)
+      end
+
+      # Get all supported language codes
+      # @return [Array<String>] Array of all supported language codes
+      def self.all
+        CODES
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/version.rb

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

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Notifications of messaging limit, business profile, and Official Business
+    # Account 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 AccountAlerts
+      # @!attribute [rw] entity_type
+      #   @return [String, nil]
+      attr_accessor :entity_type
+
+      # @!attribute [rw] entity_id
+      #   @return [String, nil]
+      attr_accessor :entity_id
+
+      # @!attribute [rw] alert_severity
+      #   @return [String, nil]
+      attr_accessor :alert_severity
+
+      # @!attribute [rw] alert_status
+      #   @return [String, nil]
+      attr_accessor :alert_status
+
+      # @!attribute [rw] alert_description
+      #   @return [String, nil]
+      attr_accessor :alert_description
+
+      def initialize(entity_type:, entity_id:, alert_severity:, alert_status:, alert_description:)
+        @entity_type = entity_type
+        @entity_id = entity_id
+        @alert_severity = alert_severity
+        @alert_status = alert_status
+        @alert_description = alert_description
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [AccountAlerts]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            entity_type: data["entity_type"],
+            entity_id: data["entity_id"],
+            alert_severity: data["alert_severity"],
+            alert_status: data["alert_status"],
+            alert_description: data["alert_description"]
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Policy guideline review outcomes for WhatsApp Business Accounts.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+    class AccountReviewUpdate
+      # @!attribute [rw] decision
+      #   @return [String, nil] e.g. `"APPROVED"`, `"REJECTED"`.
+      attr_accessor :decision
+
+      def initialize(decision:)
+        @decision = decision
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [AccountReviewUpdate]
+        def deserialize(data)
+          data ||= {}
+
+          new(decision: data["decision"])
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/account_update/ban_info.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class AccountUpdate
+      # The ban details attached to an `account_update` notification.
+      class BanInfo
+        # @!attribute [rw] waba_ban_state
+        #   @return [String, nil]
+        attr_accessor :waba_ban_state
+
+        # @!attribute [rw] waba_ban_date
+        #   @return [String, nil]
+        attr_accessor :waba_ban_date
+
+        def initialize(waba_ban_state:, waba_ban_date:)
+          @waba_ban_state = waba_ban_state
+          @waba_ban_date = waba_ban_date
+        end
+
+        class << self
+          # @param data [Hash] The raw `ban_info` hash.
+          # @return [BanInfo]
+          def deserialize(data)
+            data ||= {}
+
+            new(waba_ban_state: data["waba_ban_state"], waba_ban_date: data["waba_ban_date"])
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Partner-led verification, authentication rates, primary location, policy
+    # violations, offboarding, reconnection, or deletion of a WhatsApp Business Account.
+    #
+    # 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 AccountUpdate
+      # @!attribute [rw] phone_number
+      #   @return [String, nil]
+      attr_accessor :phone_number
+
+      # @!attribute [rw] event
+      #   @return [String, nil] e.g. `"VERIFIED_ACCOUNT"`, `"DISABLED_UPDATE"`, `"PARTNER_APP_INSTALLED"`.
+      attr_accessor :event
+
+      # @!attribute [rw] ban_info
+      #   @return [BanInfo, nil]
+      attr_accessor :ban_info
+
+      def initialize(phone_number:, event:, ban_info: nil)
+        @phone_number = phone_number
+        @event = event
+        @ban_info = ban_info
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [AccountUpdate]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            phone_number: data["phone_number"],
+            event: data["event"],
+            ban_info: data["ban_info"] ? BanInfo.deserialize(data["ban_info"]) : nil
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Purchase or lead event detection from Click to WhatsApp ad conversations.
+    #
+    # Best-effort schema: Meta's public docs describe this field in one line with
+    # no published JSON example; `event_data`'s nested 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 AutomaticEvents
+      # @!attribute [rw] event_type
+      #   @return [String, nil] e.g. `"purchase"`, `"lead"`.
+      attr_accessor :event_type
+
+      # @!attribute [rw] message_id
+      #   @return [String, nil]
+      attr_accessor :message_id
+
+      # @!attribute [rw] event_data
+      #   @return [Hash]
+      attr_accessor :event_data
+
+      def initialize(event_type:, message_id:, event_data:)
+        @event_type = event_type
+        @message_id = message_id
+        @event_data = event_data
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [AutomaticEvents]
+        def deserialize(data)
+          data ||= {}
+
+          new(event_type: data["event_type"], message_id: data["message_id"], event_data: data["event_data"] || {})
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Messaging limits, phone number limits, and capability changes for a
+    # WhatsApp Business Account.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+    class BusinessCapabilityUpdate
+      # @!attribute [rw] max_daily_conversation_per_phone
+      #   @return [Integer, nil]
+      attr_accessor :max_daily_conversation_per_phone
+
+      # @!attribute [rw] max_phone_numbers_per_business
+      #   @return [Integer, nil]
+      attr_accessor :max_phone_numbers_per_business
+
+      def initialize(max_daily_conversation_per_phone:, max_phone_numbers_per_business:)
+        @max_daily_conversation_per_phone = max_daily_conversation_per_phone
+        @max_phone_numbers_per_business = max_phone_numbers_per_business
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [BusinessCapabilityUpdate]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            max_daily_conversation_per_phone: data["max_daily_conversation_per_phone"],
+            max_phone_numbers_per_business: data["max_phone_numbers_per_business"]
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # A single `entry[].changes[]` item: `field` names which of Meta's ~19 documented
+    # webhook notification types this is, `value` is the deserialized payload for it.
+    #
+    # `FIELDS` is populated incrementally as each field's value class is implemented
+    # (see Whatsapp::Webhook::CLAUDE.md) — never `const_get` on the field name, which
+    # comes straight from the internet; a field not yet in the registry falls back to
+    # {UnknownField} rather than raising.
+    class Change
+      FIELDS = {
+        messages: Messages,
+        account_alerts: AccountAlerts,
+        account_review_update: AccountReviewUpdate,
+        account_update: AccountUpdate,
+        automatic_events: AutomaticEvents,
+        business_capability_update: BusinessCapabilityUpdate,
+        history: History,
+        message_template_components_update: MessageTemplateComponentsUpdate,
+        message_template_quality_update: MessageTemplateQualityUpdate,
+        message_template_status_update: MessageTemplateStatusUpdate,
+        partner_solutions: PartnerSolutions,
+        payment_configuration_update: PaymentConfigurationUpdate,
+        phone_number_name_update: PhoneNumberNameUpdate,
+        phone_number_quality_update: PhoneNumberQualityUpdate,
+        security: Security,
+        smb_app_state_sync: SmbAppStateSync,
+        smb_message_echoes: SmbMessageEchoes,
+        template_category_update: TemplateCategoryUpdate,
+        user_preferences: UserPreferences,
+      }.freeze
+
+      # @!attribute [rw] field
+      #   @return [String]
+      attr_accessor :field
+
+      # @!attribute [rw] value
+      #   @return [Object] One of the classes registered in {FIELDS}, or {UnknownField}.
+      attr_accessor :value
+
+      def initialize(field:, value:)
+        @field = field
+        @value = value
+      end
+
+      class << self
+        # @param data [Hash] A raw `changes[]` entry.
+        # @return [Change]
+        def deserialize(data)
+          data ||= {}
+          field = data["field"]
+          klass = FIELDS.fetch(field.to_s.to_sym) { UnknownField }
+
+          new(field:, value: klass.deserialize(data["value"]))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # A value-level `contacts[]` entry — identifies the WhatsApp user tied to a
+    # notification (distinct from `Message::Contacts`, the inbound "share a contact
+    # card" message type, which has its own richer shape).
+    class Contact
+      # @!attribute [rw] profile_name
+      #   @return [String, nil]
+      attr_accessor :profile_name
+
+      # @!attribute [rw] wa_id
+      #   @return [String, nil]
+      attr_accessor :wa_id
+
+      def initialize(profile_name:, wa_id:)
+        @profile_name = profile_name
+        @wa_id = wa_id
+      end
+
+      class << self
+        # @param data [Hash] A raw `contacts[]` entry.
+        # @return [Contact]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            profile_name: data.dig("profile", "name"),
+            wa_id: data["wa_id"]
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # A single `entry[]` item — one WhatsApp Business Account, with one or more
+    # `changes[]` (each a distinct notification).
+    class Entry
+      # @!attribute [rw] id
+      #   @return [String]
+      attr_accessor :id
+
+      # @!attribute [rw] changes
+      #   @return [Array<Change>]
+      attr_accessor :changes
+
+      def initialize(id:, changes:)
+        @id = id
+        @changes = changes
+      end
+
+      class << self
+        # @param data [Hash] A raw `entry[]` item.
+        # @return [Entry]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            id: data["id"],
+            changes: Array(data["changes"]).map { |change_data| Change.deserialize(change_data) }
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # An error entry, present on message/status payloads that couldn't be fully
+    # processed (e.g. an unsupported message type, or a failed delivery).
+    class Error
+      # @!attribute [rw] code
+      #   @return [Integer, nil]
+      attr_accessor :code
+
+      # @!attribute [rw] title
+      #   @return [String, nil]
+      attr_accessor :title
+
+      # @!attribute [rw] message
+      #   @return [String, nil]
+      attr_accessor :message
+
+      # @!attribute [rw] details
+      #   @return [String, nil]
+      attr_accessor :details
+
+      def initialize(code:, title:, message:, details: nil)
+        @code = code
+        @title = title
+        @message = message
+        @details = details
+      end
+
+      class << self
+        # @param data [Hash] A raw `errors[]` entry.
+        # @return [Error]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            code: data["code"],
+            title: data["title"],
+            message: data["message"],
+            details: data.dig("error_data", "details")
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Chat history synchronization for onboarded business customers.
+    #
+    # Best-effort schema: Meta's public docs describe this field in one line with
+    # no published JSON example; `threads`' entry shape isn't confidently
+    # typeable from that description alone, so it's kept as a raw array 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 History
+      # @!attribute [rw] phase
+      #   @return [Integer, nil]
+      attr_accessor :phase
+
+      # @!attribute [rw] chunk_order
+      #   @return [Integer, nil]
+      attr_accessor :chunk_order
+
+      # @!attribute [rw] progress
+      #   @return [Integer, nil]
+      attr_accessor :progress
+
+      # @!attribute [rw] threads
+      #   @return [Array<Hash>]
+      attr_accessor :threads
+
+      def initialize(phase:, chunk_order:, progress:, threads:)
+        @phase = phase
+        @chunk_order = chunk_order
+        @progress = progress
+        @threads = threads
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [History]
+        def deserialize(data)
+          data ||= {}
+          metadata = data["metadata"] || {}
+
+          new(
+            phase: metadata["phase"],
+            chunk_order: metadata["chunk_order"],
+            progress: metadata["progress"],
+            threads: Array(data["threads"])
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Copies a personalizable webhook controller into a host Rails app. Plain
+    # Ruby with no Rails dependency of its own, so it can be unit tested against
+    # a plain directory — `lib/tasks/whatsapp.rake` is the thin Rails-facing
+    # wrapper around this.
+    class Installer
+      TEMPLATE_PATH = File.expand_path("templates/webhooks_controller.rb.tt", __dir__)
+      DESTINATION = "app/controllers/whatsapp/webhooks_controller.rb"
+
+      NEXT_STEPS = <<~TEXT
+        Next steps:
+
+        1. Add these routes to config/routes.rb:
+
+             get  "/whatsapp/webhooks", to: "whatsapp/webhooks#verify"
+             post "/whatsapp/webhooks", to: "whatsapp/webhooks#receive"
+
+        2. Configure your verify token and app secret, e.g. in config/initializers/whatsapp.rb:
+
+             Whatsapp.configure do |config|
+               config.verify_token = Rails.application.credentials.whatsapp_verify_token
+               config.app_secret    = Rails.application.credentials.whatsapp_app_secret
+             end
+
+        3. Personalize app/controllers/whatsapp/webhooks_controller.rb — it's your file now.
+      TEXT
+
+      class << self
+        # @param root [String] The host app's root directory.
+        # @param output [IO] Where to print progress and next steps.
+        # @return [Symbol] `:created` or `:skipped` (an existing controller is never overwritten).
+        def call(root: Dir.pwd, output: $stdout)
+          destination = File.join(root, DESTINATION)
+          result = write_controller(destination, output)
+
+          output.puts
+          output.puts NEXT_STEPS
+
+          result
+        end
+
+      private
+
+        def write_controller(destination, output)
+          if File.exist?(destination)
+            output.puts "Skipped: #{DESTINATION} already exists."
+            return :skipped
+          end
+
+          FileUtils.mkdir_p(File.dirname(destination))
+          FileUtils.cp(TEMPLATE_PATH, destination)
+          output.puts "Created #{DESTINATION}"
+          :created
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # An inbound audio message (voice note or audio clip).
+      class Audio < Media
+        # @!attribute [rw] voice
+        #   @return [Boolean, nil] Whether this was recorded as a voice note.
+        attr_accessor :voice
+
+        def initialize(voice: nil, **media_and_base_attributes)
+          super(**media_and_base_attributes)
+
+          @voice = voice
+        end
+
+        class << self
+          # @param data [Hash] The raw message hash.
+          # @return [Audio]
+          def deserialize(data)
+            new(voice: data.dig("audio", "voice"), **media_attributes(data, "audio"), **common_attributes(data))
+          end
+        end
+      end
+    end
+  end
+end