chat_sdk-whatsapp 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5a9c659c8408890113cd3a76002744ec05805a84b7f931bc3f5af5d3c8f12b92
+  data.tar.gz: f75e6904f0de6b2f29b3a7b069abc773044a31cfb189aa4f92ba9b25a9a1ef62
+SHA512:
+  metadata.gz: 2a38e860754f4f1950c9e1353e46a1ab26bd16ab2e8ef4c18861ec79fc2a4a8d17c9a1e79b8e3a2bd8e6b2d305f74f6c08ebbb1a83c6dabc5274c5ab2c841113
+  data.tar.gz: 7b1be833a9084bd3e65b7a9ba27c795b61323115ae7c0457a3ab24bec9a26e95375f6de6d638f3c56def3895362ebee343df067aa555d0f3c87c21dbdf4569e1

data/lib/chat_sdk/whatsapp/adapter.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "rack/utils"
+
+module ChatSDK
+  module WhatsApp
+    class Adapter < ChatSDK::Adapter::Base
+      capabilities :direct_messages, :file_uploads, :reactions
+
+      attr_reader :client
+
+      def initialize(access_token: nil, app_secret: nil, phone_number_id: nil, verify_token: nil)
+        @access_token = access_token || ENV["WHATSAPP_ACCESS_TOKEN"]
+        @app_secret = app_secret || ENV["WHATSAPP_APP_SECRET"]
+        @phone_number_id = phone_number_id || ENV["WHATSAPP_PHONE_NUMBER_ID"]
+        @verify_token = verify_token || ENV["WHATSAPP_VERIFY_TOKEN"]
+
+        raise ChatSDK::ConfigurationError, "WhatsApp access_token required" unless @access_token
+        raise ChatSDK::ConfigurationError, "WhatsApp phone_number_id required" unless @phone_number_id
+
+        @client = ApiClient.new(@access_token, @phone_number_id)
+        @renderer = InteractiveRenderer.new
+      end
+
+      def name
+        :whatsapp
+      end
+
+      # Inbound
+      def verify_request!(rack_request)
+        signature = rack_request.get_header("HTTP_X_HUB_SIGNATURE_256")
+
+        unless signature
+          raise ChatSDK::SignatureVerificationError, "Missing WhatsApp signature header"
+        end
+
+        body = rack_request.body.read
+        rack_request.body.rewind
+
+        expected = "sha256=#{OpenSSL::HMAC.hexdigest("SHA256", @app_secret, body)}"
+
+        unless Rack::Utils.secure_compare(signature, expected)
+          raise ChatSDK::SignatureVerificationError, "Invalid WhatsApp signature"
+        end
+
+        true
+      end
+
+      def ack_response(rack_request)
+        return nil unless rack_request.get?
+
+        params = rack_request.params
+        mode = params["hub.mode"]
+        token = params["hub.verify_token"]
+        challenge = params["hub.challenge"]
+
+        if mode == "subscribe" && token == @verify_token
+          [200, {}, [challenge.to_s]]
+        end
+      end
+
+      def parse_events(rack_request)
+        body = rack_request.body.read
+        rack_request.body.rewind
+
+        payload = JSON.parse(body)
+        EventParser.parse(payload, @phone_number_id)
+      rescue JSON::ParserError
+        []
+      end
+
+      # Outbound
+      def post_message(channel_id:, message:, thread_id: nil) # rubocop:disable Lint/UnusedMethodArgument
+        payload = prepare_message_payload(message)
+
+        result = @client.send_message(to: channel_id, **payload)
+
+        parse_whatsapp_message(result, channel_id)
+      end
+
+      def upload_file(channel_id:, io:, filename:, thread_id: nil, comment: nil) # rubocop:disable Lint/UnusedMethodArgument
+        content_type = detect_content_type(filename)
+        media_type = media_type_for(content_type)
+
+        # Upload media first
+        media_result = @client.upload_media(io: io, filename: filename, content_type: content_type)
+        media_id = media_result["id"]
+
+        # Send media message
+        media_payload = {caption: comment}.compact
+        result = @client.send_message(to: channel_id, type: media_type, **{media_type => media_payload.merge(id: media_id)})
+
+        parse_whatsapp_message(result, channel_id)
+      end
+
+      def add_reaction(channel_id:, message_id:, emoji:)
+        @client.send_reaction(to: channel_id, message_id: message_id, emoji: emoji)
+      end
+
+      def remove_reaction(channel_id:, message_id:, emoji: "") # rubocop:disable Lint/UnusedMethodArgument
+        @client.send_reaction(to: channel_id, message_id: message_id, emoji: "")
+      end
+
+      def open_dm(user_id)
+        user_id
+      end
+
+      def mention(user_id)
+        user_id
+      end
+
+      def render(postable_message)
+        if postable_message.card?
+          @renderer.render(postable_message.card)
+        else
+          postable_message.text
+        end
+      end
+
+      private
+
+      def prepare_message_payload(message)
+        msg = ChatSDK::PostableMessage.from(message)
+
+        if msg.card?
+          rendered = @renderer.render(msg.card)
+          if rendered.is_a?(Hash) && rendered[:type] == "interactive"
+            {type: "interactive", interactive: rendered[:interactive]}
+          else
+            {type: "text", text: {body: rendered[:text] || msg.text || msg.card.fallback_text || ""}}
+          end
+        else
+          {type: "text", text: {body: msg.text || ""}}
+        end
+      end
+
+      def parse_whatsapp_message(data, channel_id)
+        message_id = data.dig("messages", 0, "id")
+
+        ChatSDK::Message.new(
+          id: message_id,
+          text: "",
+          author: ChatSDK::Author.new(
+            id: "bot",
+            name: "bot",
+            platform: :whatsapp,
+            bot: true
+          ),
+          thread_id: "whatsapp:#{@phone_number_id}:#{channel_id}",
+          channel_id: channel_id,
+          platform: :whatsapp,
+          raw: data
+        )
+      end
+
+      CONTENT_TYPES = {
+        ".jpg" => "image/jpeg", ".jpeg" => "image/jpeg", ".png" => "image/png",
+        ".gif" => "image/gif", ".webp" => "image/webp",
+        ".mp4" => "video/mp4", ".3gp" => "video/3gpp",
+        ".mp3" => "audio/mpeg", ".ogg" => "audio/ogg", ".amr" => "audio/amr",
+        ".pdf" => "application/pdf", ".doc" => "application/msword",
+        ".docx" => "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        ".xls" => "application/vnd.ms-excel",
+        ".xlsx" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+      }.freeze
+
+      def detect_content_type(filename)
+        CONTENT_TYPES.fetch(File.extname(filename).downcase, "application/octet-stream")
+      end
+
+      def media_type_for(content_type)
+        case content_type
+        when %r{^image/} then "image"
+        when %r{^video/} then "video"
+        when %r{^audio/} then "audio"
+        else "document"
+        end
+      end
+    end
+  end
+end

data/lib/chat_sdk/whatsapp/api_client.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module WhatsApp
+    class ApiClient
+      BASE_URL = "https://graph.facebook.com/v21.0"
+
+      def initialize(access_token, phone_number_id)
+        @access_token = access_token
+        @phone_number_id = phone_number_id
+      end
+
+      def send_message(to:, type:, **payload)
+        body = {
+          "messaging_product" => "whatsapp",
+          "recipient_type" => "individual",
+          "to" => to,
+          "type" => type
+        }.merge(payload)
+
+        request(:post, "#{@phone_number_id}/messages", body)
+      end
+
+      def send_reaction(to:, message_id:, emoji:)
+        send_message(
+          to: to,
+          type: "reaction",
+          reaction: {message_id: message_id, emoji: emoji}
+        )
+      end
+
+      def upload_media(io:, filename:, content_type:)
+        response = media_connection.post("#{@phone_number_id}/media") do |req|
+          req.body = {
+            "messaging_product" => "whatsapp",
+            "file" => Faraday::Multipart::FilePart.new(io, content_type, filename),
+            "type" => content_type
+          }
+        end
+
+        handle_response(response)
+      end
+
+      private
+
+      def connection
+        @connection ||= build_connection { |f| f.request :json }
+      end
+
+      def media_connection
+        @media_connection ||= build_connection { |f| f.request :multipart }
+      end
+
+      def build_connection
+        Faraday.new(url: BASE_URL) do |f|
+          yield f
+          f.response :json
+          f.adapter :net_http
+          f.headers["Authorization"] = "Bearer #{@access_token}"
+        end
+      end
+
+      def request(method, path, body = nil)
+        response = connection.public_send(method, path) do |req|
+          req.body = body if body && method != :get
+        end
+
+        handle_response(response)
+      end
+
+      def handle_response(response)
+        body = response.body
+        return body.is_a?(Hash) ? body : {} if response.success?
+
+        if response.status == 429
+          raise ChatSDK::RateLimitedError.new(
+            "WhatsApp API rate limited",
+            retry_after: nil,
+            status: response.status,
+            body: body,
+            adapter_name: :whatsapp
+          )
+        end
+
+        error_message = body.is_a?(Hash) ? body.dig("error", "message") : response.status
+        raise ChatSDK::PlatformError.new(
+          "WhatsApp API error: #{error_message}",
+          status: response.status,
+          body: body,
+          adapter_name: :whatsapp
+        )
+      end
+    end
+  end
+end

data/lib/chat_sdk/whatsapp/event_parser.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module WhatsApp
+    class EventParser
+      class << self
+        def parse(payload, phone_number_id)
+          return [] unless payload.is_a?(Hash)
+          return [] unless payload["object"] == "whatsapp_business_account"
+
+          (payload["entry"] || [])
+            .flat_map { |entry| entry["changes"] || [] }
+            .select { |change| change["field"] == "messages" }
+            .flat_map { |change| change.dig("value", "messages") || [] }
+            .filter_map { |msg| parse_message(msg, phone_number_id) }
+        end
+
+        private
+
+        def parse_message(msg, phone_number_id)
+          from = msg["from"]&.to_s
+          return nil unless from
+
+          author = ChatSDK::Author.new(id: from, name: from, platform: :whatsapp, bot: false)
+          thread_id = "whatsapp:#{phone_number_id}:#{from}"
+
+          case msg["type"]
+          when "text"
+            build_direct_message(msg, msg.dig("text", "body") || "", author, from, thread_id)
+          when "interactive"
+            parse_interactive_message(msg, author, from, thread_id)
+          when "image", "document", "audio", "video"
+            parse_media_message(msg, author, from, thread_id)
+          end
+        end
+
+        def parse_interactive_message(msg, author, channel_id, thread_id)
+          interactive = msg["interactive"] || {}
+          action_id = interactive.dig("button_reply", "id") || interactive.dig("list_reply", "id") || ""
+
+          ChatSDK::Events::Action.new(
+            action_id: action_id,
+            value: action_id,
+            user: author,
+            thread_id: thread_id,
+            channel_id: channel_id,
+            platform: :whatsapp,
+            adapter_name: :whatsapp,
+            raw: msg
+          )
+        end
+
+        def parse_media_message(msg, author, channel_id, thread_id)
+          media_type = msg["type"]
+          media_data = msg[media_type] || {}
+          caption = media_data["caption"] || ""
+          mime_type = media_data["mime_type"] || ""
+          media_id = media_data["id"] || ""
+
+          text = [caption, "[#{media_type}: #{mime_type} #{media_id}]"].reject(&:empty?).join("\n")
+          build_direct_message(msg, text, author, channel_id, thread_id)
+        end
+
+        def build_direct_message(msg, text, author, channel_id, thread_id)
+          message = ChatSDK::Message.new(
+            id: msg["id"],
+            text: text,
+            author: author,
+            thread_id: thread_id,
+            channel_id: channel_id,
+            platform: :whatsapp,
+            raw: msg
+          )
+
+          ChatSDK::Events::DirectMessage.new(
+            message: message,
+            thread_id: thread_id,
+            channel_id: channel_id,
+            platform: :whatsapp,
+            adapter_name: :whatsapp,
+            raw: msg
+          )
+        end
+      end
+    end
+  end
+end

data/lib/chat_sdk/whatsapp/interactive_renderer.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module ChatSDK
+  module WhatsApp
+    class InteractiveRenderer
+      def render(node)
+        case node.type
+        when :card then render_card(node)
+        else render_single(node)
+        end
+      end
+
+      private
+
+      def render_card(node)
+        buttons = collect_reply_buttons(node)
+        title = node.attributes[:title]
+        subtitle = node.attributes[:subtitle]
+        text_parts = collect_text_parts(node)
+        body_text = [subtitle, *text_parts].compact.reject(&:empty?).join("\n")
+        body_text = title if body_text.empty?
+
+        if title && buttons.any? && buttons.length <= 3
+          interactive = {
+            "type" => "button",
+            "body" => {"text" => body_text}
+          }
+          interactive["header"] = {"type" => "text", "text" => truncate(title, 60)} if title
+          interactive["action"] = {
+            "buttons" => buttons.first(3).map do |btn|
+              {
+                "type" => "reply",
+                "reply" => {
+                  "id" => btn[:id],
+                  "title" => truncate(btn[:text], 20)
+                }
+              }
+            end
+          }
+
+          {type: "interactive", interactive: interactive}
+        else
+          # Fallback to plain text
+          fallback = [title, subtitle, *text_parts].compact.reject(&:empty?).join("\n")
+          if buttons.any?
+            button_text = buttons.map { |b| b[:text] }.join(", ")
+            fallback = "#{fallback}\n[#{button_text}]" unless button_text.empty?
+          end
+          {text: fallback}
+        end
+      end
+
+      def collect_reply_buttons(node)
+        buttons = []
+        node.children.each do |child|
+          case child.type
+          when :button
+            buttons << {id: child.attributes[:id] || "button", text: child.attributes[:text] || ""}
+          when :link_button
+            # WhatsApp reply buttons can't have URLs; skip link buttons
+            next
+          when :actions
+            child.children.each do |action_child|
+              case action_child.type
+              when :button
+                buttons << {id: action_child.attributes[:id] || "button", text: action_child.attributes[:text] || ""}
+              when :link_button
+                next
+              end
+            end
+          when :section
+            buttons.concat(collect_reply_buttons(child))
+          end
+        end
+        buttons
+      end
+
+      def collect_text_parts(node)
+        parts = []
+        node.children.each do |child|
+          case child.type
+          when :text
+            parts << child.attributes[:content]
+          when :divider
+            parts << "---"
+          when :fields
+            child.children.each do |field|
+              parts << "#{field.attributes[:label]}: #{field.attributes[:value]}"
+            end
+          when :section
+            parts << child.attributes[:title] if child.attributes[:title]
+            parts.concat(collect_text_parts(child))
+          end
+        end
+        parts
+      end
+
+      def render_single(node)
+        case node.type
+        when :text
+          {text: node.attributes[:content]}
+        else
+          {text: node.fallback_text}
+        end
+      end
+
+      def truncate(text, max)
+        return "" unless text
+
+        (text.length > max) ? "#{text[0..max - 4]}..." : text
+      end
+    end
+  end
+end

data/lib/chat_sdk/whatsapp.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "chat_sdk"
+require "faraday"
+require "faraday/net_http"
+require "zeitwerk"
+
+module ChatSDK
+  module WhatsApp
+    class << self
+      def loader
+        @loader ||= begin
+          loader = Zeitwerk::Loader.new
+          loader.tag = "chat_sdk-whatsapp"
+          loader.inflector.inflect("chat_sdk" => "ChatSDK", "whatsapp" => "WhatsApp")
+          loader.push_dir("#{__dir__}/whatsapp", namespace: ChatSDK::WhatsApp)
+          loader.setup
+          loader
+        end
+      end
+    end
+  end
+end
+
+ChatSDK::WhatsApp.loader

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: chat_sdk-whatsapp
+version: !ruby/object:Gem::Version
+  version: 0.2.1
+platform: ruby
+authors:
+- Quentin Rousseau
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: chat_sdk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: WhatsApp Business Cloud API adapter for the ChatSDK framework with HMAC-SHA256
+  verification and interactive message rendering
+email:
+- quentin@rootly.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/chat_sdk/whatsapp.rb
+- lib/chat_sdk/whatsapp/adapter.rb
+- lib/chat_sdk/whatsapp/api_client.rb
+- lib/chat_sdk/whatsapp/event_parser.rb
+- lib/chat_sdk/whatsapp/interactive_renderer.rb
+homepage: https://github.com/rootlyhq/chat-sdk
+licenses:
+- MIT
+metadata:
+  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: 4.0.16
+specification_version: 4
+summary: WhatsApp Business Cloud API adapter for ChatSDK
+test_files: []