ruby-whatsapp 0.3.0

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Template category changes and re-categorization corrections.
+    #
+    # 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 TemplateCategoryUpdate
+      # @!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_category
+      #   @return [String, nil]
+      attr_accessor :previous_category
+
+      # @!attribute [rw] new_category
+      #   @return [String, nil]
+      attr_accessor :new_category
+
+      # @!attribute [rw] correct_category
+      #   @return [String, nil]
+      attr_accessor :correct_category
+
+      def initialize(message_template_id:, message_template_name:, message_template_language:,
+        previous_category:, new_category:, correct_category: nil)
+        @message_template_id = message_template_id
+        @message_template_name = message_template_name
+        @message_template_language = message_template_language
+        @previous_category = previous_category
+        @new_category = new_category
+        @correct_category = correct_category
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [TemplateCategoryUpdate]
+        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_category: data["previous_category"],
+            new_category: data["new_category"],
+            correct_category: data["correct_category"]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/templates/webhooks_controller.rb.tt

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class WebhooksController < ApplicationController
+    skip_before_action :verify_authenticity_token, raise: false
+
+    # GET — Meta calls this once when you save the callback URL in the App Dashboard.
+    def verify
+      challenge = Whatsapp::Webhook::Verification.call(params: params)
+      return head :forbidden unless challenge
+
+      render plain: challenge
+    end
+
+    # POST — Meta calls this for every event notification.
+    def receive
+      raw_body = request.body.read
+
+      unless Whatsapp::Webhook::Signature.valid?(payload: raw_body, header: request.headers["X-Hub-Signature-256"])
+        return head :unauthorized
+      end
+
+      notification = Whatsapp::Webhook::Notification.deserialize(JSON.parse(raw_body))
+
+      # TODO: your business logic here, e.g.:
+      # notification.entry.each { |entry| entry.changes.each { |change| WebhookJob.perform_later(change) } }
+
+      head :ok
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Fallback value wrapper for any webhook `field` not in {Change::FIELDS} — either
+    # a field Meta added after this gem was released, or one deliberately left generic.
+    # Keeps the raw hash accessible instead of raising on an unrecognized notification.
+    class UnknownField
+      # @!attribute [r] raw
+      #   @return [Hash]
+      attr_reader :raw
+
+      def initialize(raw:)
+        @raw = raw
+      end
+
+      # @param key [String]
+      # @return [Object, nil]
+      def [](key)
+        raw[key]
+      end
+
+      # @return [Hash]
+      def to_h
+        raw
+      end
+
+      class << self
+        # @param data [Hash, nil] The raw `value` hash.
+        # @return [UnknownField]
+        def deserialize(data)
+          new(raw: data || {})
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # User marketing message preference changes (e.g. a customer opting out of
+    # marketing messages).
+    #
+    # 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 UserPreferences
+      # @!attribute [rw] wa_id
+      #   @return [String, nil]
+      attr_accessor :wa_id
+
+      # @!attribute [rw] detail
+      #   @return [String, nil]
+      attr_accessor :detail
+
+      # @!attribute [rw] value
+      #   @return [String, nil] e.g. `"stop"`, `"resume"`.
+      attr_accessor :value
+
+      # @!attribute [rw] timestamp
+      #   @return [String, nil]
+      attr_accessor :timestamp
+
+      def initialize(wa_id:, detail:, value:, timestamp:)
+        @wa_id = wa_id
+        @detail = detail
+        @value = value
+        @timestamp = timestamp
+      end
+
+      class << self
+        # @param data [Hash] The raw `value` hash.
+        # @return [UserPreferences]
+        def deserialize(data)
+          data ||= {}
+
+          new(wa_id: data["wa_id"], detail: data["detail"], value: data["value"], timestamp: data["timestamp"])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # Handles the one-time GET handshake Meta sends when a webhook callback URL is
+    # registered in the App Dashboard: `hub.mode`, `hub.verify_token`, `hub.challenge`.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+    class Verification
+      class << self
+        # @param params [Hash] The request params, string-keyed as Rails provides them
+        #   (e.g. `params["hub.mode"]`, `params["hub.verify_token"]`, `params["hub.challenge"]`).
+        # @param verify_token [String, nil] The token to check against. Defaults to the
+        #   globally configured token; pass an explicit value for multi-tenant apps where
+        #   each account has its own token.
+        # @return [String, nil] The `hub.challenge` value to echo back, or `nil` if the
+        #   request doesn't match a subscribe handshake with the expected token.
+        def call(params:, verify_token: Whatsapp.configuration.verify_token)
+          return unless params["hub.mode"] == "subscribe"
+          return if verify_token.nil? || verify_token.empty?
+          return unless ActiveSupport::SecurityUtils.secure_compare(params["hub.verify_token"].to_s, verify_token)
+
+          params["hub.challenge"]
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  # Deserializes and authenticates incoming WhatsApp Cloud API webhook notifications.
+  # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+  module Webhook
+  end
+end

data/lib/ruby/whatsapp.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "json"
+require "logger"
+require "uri"
+require "http"
+require "zeitwerk"
+require "active_model"
+require "active_support/security_utils"
+require "openssl"
+require "fileutils"
+
+loader = Zeitwerk::Loader.for_gem
+loader.collapse(__dir__)
+# The Railtie must be required eagerly (below), not autoloaded, so it's excluded here.
+loader.ignore("#{__dir__}/whatsapp/railtie.rb")
+loader.setup
+
+module Whatsapp
+  class Error < StandardError; end
+
+  class << self
+    attr_writer :configuration
+
+    # Returns the global configuration, lazily initializing it on first use.
+    # @return [Whatsapp::Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the configuration for mutation and returns it.
+    # @yieldparam configuration [Whatsapp::Configuration]
+    # @return [Whatsapp::Configuration]
+    def configure
+      yield(configuration) if block_given?
+
+      configuration
+    end
+  end
+end
+
+# Exposed so the whole constant tree can be eagerly loaded (used in tests to
+# guarantee every file resolves under Zeitwerk).
+Whatsapp.define_singleton_method(:eager_load!) { loader.eager_load }
+
+# Rails discovers Railtie subclasses at boot by class definition, so this must be
+# required eagerly (never autoloaded) — and only when Rails is actually present,
+# since this gem has no Rails dependency of its own.
+require_relative "whatsapp/railtie" if defined?(Rails::Railtie)

data/lib/tasks/whatsapp.rake

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+namespace :whatsapp do
+  namespace :install do
+    desc "Install a personalizable WhatsApp webhook controller into this Rails app"
+    task webhook: :environment do
+      Whatsapp::Webhook::Installer.call(root: Rails.root)
+    end
+  end
+end

data/sig/ruby/whatsapp.rbs

@@ -0,0 +1,6 @@
+module Ruby
+  module Whatsapp
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,267 @@
+--- !ruby/object:Gem::Specification
+name: ruby-whatsapp
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Raniery
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: 'A small, dependency-light Ruby client for the Meta WhatsApp Cloud API:
+  send text, media, template, interactive, and other message types, and upload, download,
+  and manage media assets.'
+email:
+- raniery@saleszera.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/ruby/whatsapp.rb
+- lib/ruby/whatsapp/client.rb
+- lib/ruby/whatsapp/configuration.rb
+- lib/ruby/whatsapp/instrumentation.rb
+- lib/ruby/whatsapp/media.rb
+- lib/ruby/whatsapp/message_templates.rb
+- lib/ruby/whatsapp/message_templates/button.rb
+- lib/ruby/whatsapp/message_templates/button/base.rb
+- lib/ruby/whatsapp/message_templates/button/copy_code.rb
+- lib/ruby/whatsapp/message_templates/button/otp.rb
+- lib/ruby/whatsapp/message_templates/button/otp/supported_app.rb
+- lib/ruby/whatsapp/message_templates/button/phone_number.rb
+- lib/ruby/whatsapp/message_templates/button/quick_reply.rb
+- lib/ruby/whatsapp/message_templates/button/url.rb
+- lib/ruby/whatsapp/message_templates/categories.rb
+- lib/ruby/whatsapp/message_templates/component.rb
+- lib/ruby/whatsapp/message_templates/component/base.rb
+- lib/ruby/whatsapp/message_templates/component/body.rb
+- lib/ruby/whatsapp/message_templates/component/buttons.rb
+- lib/ruby/whatsapp/message_templates/component/carousel.rb
+- lib/ruby/whatsapp/message_templates/component/carousel/card.rb
+- lib/ruby/whatsapp/message_templates/component/footer.rb
+- lib/ruby/whatsapp/message_templates/component/header.rb
+- lib/ruby/whatsapp/message_templates/component/limited_time_offer.rb
+- lib/ruby/whatsapp/message_templates/component_set.rb
+- lib/ruby/whatsapp/message_templates/example.rb
+- lib/ruby/whatsapp/message_templates/library_template.rb
+- lib/ruby/whatsapp/message_templates/library_template/body_inputs.rb
+- lib/ruby/whatsapp/message_templates/library_template/button_inputs.rb
+- lib/ruby/whatsapp/message_templates/parameter_formats.rb
+- lib/ruby/whatsapp/message_templates/placeholders.rb
+- lib/ruby/whatsapp/message_templates/response.rb
+- lib/ruby/whatsapp/message_templates/response/collection.rb
+- lib/ruby/whatsapp/message_templates/response/created.rb
+- lib/ruby/whatsapp/message_templates/response/node.rb
+- lib/ruby/whatsapp/message_templates/response/paging.rb
+- lib/ruby/whatsapp/message_templates/response/quality_score.rb
+- lib/ruby/whatsapp/message_templates/response/summary.rb
+- lib/ruby/whatsapp/message_templates/statuses.rb
+- lib/ruby/whatsapp/message_templates/template.rb
+- lib/ruby/whatsapp/message_templates/value_object.rb
+- lib/ruby/whatsapp/messages.rb
+- lib/ruby/whatsapp/messages/address.rb
+- lib/ruby/whatsapp/messages/audio.rb
+- lib/ruby/whatsapp/messages/base.rb
+- lib/ruby/whatsapp/messages/contacts.rb
+- lib/ruby/whatsapp/messages/contacts/address.rb
+- lib/ruby/whatsapp/messages/contacts/contact.rb
+- lib/ruby/whatsapp/messages/contacts/email.rb
+- lib/ruby/whatsapp/messages/contacts/name.rb
+- lib/ruby/whatsapp/messages/contacts/org.rb
+- lib/ruby/whatsapp/messages/contacts/phone.rb
+- lib/ruby/whatsapp/messages/contacts/url.rb
+- lib/ruby/whatsapp/messages/document.rb
+- lib/ruby/whatsapp/messages/image.rb
+- lib/ruby/whatsapp/messages/interactive.rb
+- lib/ruby/whatsapp/messages/interactive/base.rb
+- lib/ruby/whatsapp/messages/interactive/body.rb
+- lib/ruby/whatsapp/messages/interactive/footer.rb
+- lib/ruby/whatsapp/messages/interactive/header.rb
+- lib/ruby/whatsapp/messages/interactive/list_buttons.rb
+- lib/ruby/whatsapp/messages/interactive/list_buttons/section.rb
+- lib/ruby/whatsapp/messages/interactive/list_buttons/section/row.rb
+- lib/ruby/whatsapp/messages/interactive/media_carousel.rb
+- lib/ruby/whatsapp/messages/interactive/media_carousel/card.rb
+- lib/ruby/whatsapp/messages/interactive/media_carousel/card/button.rb
+- lib/ruby/whatsapp/messages/interactive/media_carousel/card/button/quick_reply.rb
+- lib/ruby/whatsapp/messages/interactive/product_carousel.rb
+- lib/ruby/whatsapp/messages/interactive/product_carousel/card.rb
+- lib/ruby/whatsapp/messages/interactive/reply_buttons.rb
+- lib/ruby/whatsapp/messages/interactive/reply_buttons/button.rb
+- lib/ruby/whatsapp/messages/interactive/url_button.rb
+- lib/ruby/whatsapp/messages/location.rb
+- lib/ruby/whatsapp/messages/location_request.rb
+- lib/ruby/whatsapp/messages/mark_message_as_read.rb
+- lib/ruby/whatsapp/messages/reaction.rb
+- lib/ruby/whatsapp/messages/response.rb
+- lib/ruby/whatsapp/messages/response/contacts.rb
+- lib/ruby/whatsapp/messages/response/messages.rb
+- lib/ruby/whatsapp/messages/sticker.rb
+- lib/ruby/whatsapp/messages/template.rb
+- lib/ruby/whatsapp/messages/template/component.rb
+- lib/ruby/whatsapp/messages/template/language.rb
+- lib/ruby/whatsapp/messages/template/parameter.rb
+- lib/ruby/whatsapp/messages/text.rb
+- lib/ruby/whatsapp/messages/video.rb
+- lib/ruby/whatsapp/railtie.rb
+- lib/ruby/whatsapp/request_error.rb
+- lib/ruby/whatsapp/response_handling.rb
+- lib/ruby/whatsapp/utils/language_codes.rb
+- lib/ruby/whatsapp/version.rb
+- lib/ruby/whatsapp/webhook.rb
+- lib/ruby/whatsapp/webhook/account_alerts.rb
+- lib/ruby/whatsapp/webhook/account_review_update.rb
+- lib/ruby/whatsapp/webhook/account_update.rb
+- lib/ruby/whatsapp/webhook/account_update/ban_info.rb
+- lib/ruby/whatsapp/webhook/automatic_events.rb
+- lib/ruby/whatsapp/webhook/business_capability_update.rb
+- lib/ruby/whatsapp/webhook/change.rb
+- lib/ruby/whatsapp/webhook/contact.rb
+- lib/ruby/whatsapp/webhook/entry.rb
+- lib/ruby/whatsapp/webhook/error.rb
+- lib/ruby/whatsapp/webhook/history.rb
+- lib/ruby/whatsapp/webhook/installer.rb
+- lib/ruby/whatsapp/webhook/message.rb
+- lib/ruby/whatsapp/webhook/message/audio.rb
+- lib/ruby/whatsapp/webhook/message/base.rb
+- lib/ruby/whatsapp/webhook/message/button.rb
+- lib/ruby/whatsapp/webhook/message/contacts.rb
+- lib/ruby/whatsapp/webhook/message/contacts/address.rb
+- lib/ruby/whatsapp/webhook/message/contacts/contact.rb
+- lib/ruby/whatsapp/webhook/message/contacts/email.rb
+- lib/ruby/whatsapp/webhook/message/contacts/name.rb
+- lib/ruby/whatsapp/webhook/message/contacts/org.rb
+- lib/ruby/whatsapp/webhook/message/contacts/phone.rb
+- lib/ruby/whatsapp/webhook/message/contacts/url.rb
+- lib/ruby/whatsapp/webhook/message/context.rb
+- lib/ruby/whatsapp/webhook/message/document.rb
+- lib/ruby/whatsapp/webhook/message/image.rb
+- lib/ruby/whatsapp/webhook/message/interactive.rb
+- lib/ruby/whatsapp/webhook/message/location.rb
+- lib/ruby/whatsapp/webhook/message/media.rb
+- lib/ruby/whatsapp/webhook/message/order.rb
+- lib/ruby/whatsapp/webhook/message/order/product_item.rb
+- lib/ruby/whatsapp/webhook/message/reaction.rb
+- lib/ruby/whatsapp/webhook/message/referral.rb
+- lib/ruby/whatsapp/webhook/message/sticker.rb
+- lib/ruby/whatsapp/webhook/message/system.rb
+- lib/ruby/whatsapp/webhook/message/text.rb
+- lib/ruby/whatsapp/webhook/message/unknown.rb
+- lib/ruby/whatsapp/webhook/message/video.rb
+- lib/ruby/whatsapp/webhook/message_template_components_update.rb
+- lib/ruby/whatsapp/webhook/message_template_quality_update.rb
+- lib/ruby/whatsapp/webhook/message_template_status_update.rb
+- lib/ruby/whatsapp/webhook/messages.rb
+- lib/ruby/whatsapp/webhook/metadata.rb
+- lib/ruby/whatsapp/webhook/notification.rb
+- lib/ruby/whatsapp/webhook/partner_solutions.rb
+- lib/ruby/whatsapp/webhook/payment_configuration_update.rb
+- lib/ruby/whatsapp/webhook/phone_number_name_update.rb
+- lib/ruby/whatsapp/webhook/phone_number_quality_update.rb
+- lib/ruby/whatsapp/webhook/security.rb
+- lib/ruby/whatsapp/webhook/signature.rb
+- lib/ruby/whatsapp/webhook/smb_app_state_sync.rb
+- lib/ruby/whatsapp/webhook/smb_app_state_sync/state_sync.rb
+- lib/ruby/whatsapp/webhook/smb_message_echoes.rb
+- lib/ruby/whatsapp/webhook/status.rb
+- lib/ruby/whatsapp/webhook/status/conversation.rb
+- lib/ruby/whatsapp/webhook/status/pricing.rb
+- lib/ruby/whatsapp/webhook/template_category_update.rb
+- lib/ruby/whatsapp/webhook/templates/webhooks_controller.rb.tt
+- lib/ruby/whatsapp/webhook/unknown_field.rb
+- lib/ruby/whatsapp/webhook/user_preferences.rb
+- lib/ruby/whatsapp/webhook/verification.rb
+- lib/tasks/whatsapp.rake
+- sig/ruby/whatsapp.rbs
+homepage: https://github.com/saleszera/ruby-whatsapp
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/saleszera/ruby-whatsapp
+  source_code_uri: https://github.com/saleszera/ruby-whatsapp
+  changelog_uri: https://github.com/saleszera/ruby-whatsapp/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for the Meta WhatsApp Cloud API.
+test_files: []