ask-channel-providers 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '008b3dc3ffd6f0875b93b698a46aa92c490818026cb5218be7247c11b5da1291'
-  data.tar.gz: 61d0f30d95c6c99f72de845ecd6afa9f708d178774c4145433c73a6d98e882c5
+  metadata.gz: 4aee83f6a3689cd90be057aa4c2fbe60be6ed9b2d9d03b982f068dd078da478e
+  data.tar.gz: 92375f391036782135a573601491cb94058292707598e2c6cea1a0c26838822d
 SHA512:
-  metadata.gz: 2473452ef5244df0a0c1706e8ad39cff6ff1f319c871a3e1f37d89cbfab363d9ebbcc201f3c050f2c7730990915b569f9eb45b5269cfd49586136e3dc1e461a0
-  data.tar.gz: edb38dff75b2b7a0e8b4a853ec8f7034f9a8dc8c4d9bab5b17cdca98bb2f15aee464d73e9711f39813d4c674c92943f83b5fa1a68ca2679fbcf76e536a87f9ad
+  metadata.gz: db379ca378c54dca7136fbeab036b3467afbc098ab37615899c9d4bccc4624a5008df4141d71f4f4639e7ea413dfd5d190745e18fb49c41b04560cb9f1e3a3f4
+  data.tar.gz: 3f4e8ed7b481c99aded1184c20af5af9a51a5a060bf9bef4768dcd532fb2ef343806e6ecc9849dde9251dac1f449db1f1fb47af2903f787383871c8a2959adce

data/CHANGELOG.md

@@ -5,6 +5,24 @@ following the keep-a-changelog format.
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-13
+
+### Added
+
+- `Ask::ChannelProviders::WebhookAdapter` — base class for webhook-driven
+  channels where the provider pushes to your HTTP endpoint: class-level
+  `.provider`, `.verify_signature`, `.challenge`, `.parse`, and
+  instance-level `#deliver`/`#mark_read`.
+- `Ask::ChannelProviders::InboundMessage` — one normalized inbound message
+  shape across providers, with JSON-safe `#to_h`/`.from_h` for background
+  job serialization.
+- `Ask::ChannelProviders::WhatsApp` — WhatsApp Cloud API (Meta Graph API,
+  direct): X-Hub-Signature-256 verification, webhook challenge, payload
+  parsing, and a client that sends chunked text messages and read receipts.
+- Inbound media: `InboundMessage` carries `media_id`/`media_type`, and the
+  WhatsApp client downloads attachments (`#fetch_media`) through the Graph
+  API.
+
 ## [0.1.0] - 2026-09-04
 
 ### Added

data/README.md

@@ -4,8 +4,9 @@
 
 Channel adapters for messaging platforms in the ask-rb ecosystem. It defines
 a uniform adapter interface for receiving and sending messages, approvals,
-and rich cards, plus a cross-platform card system. Only Telegram is
-implemented today; other platforms can be added by subclassing the adapter.
+and rich cards, plus a cross-platform card system. Telegram (polling) and
+WhatsApp Cloud API (webhooks) are implemented; other platforms can be added
+by subclassing the adapter.
 
 ## Installation
 
@@ -30,15 +31,51 @@ adapter.start do |msg|
 end
 ```
 
+## WhatsApp (webhooks)
+
+WhatsApp is webhook-driven: the provider POSTs to your endpoint, so
+verification and parsing are class-level and stateless, while delivery is
+bound to one phone number. Secrets are passed in — the gem never reads
+global config — so one process can serve many accounts.
+
+```ruby
+adapter_class = Ask::ChannelProviders::WhatsApp::Adapter
+
+# GET /webhooks/whatsapp — registration challenge
+challenge = adapter_class.challenge(params, verify_token: ENV["WHATSAPP_VERIFY_TOKEN"])
+
+# POST /webhooks/whatsapp — verify, then parse
+ok = adapter_class.verify_signature(
+  raw_body: request.body.read,
+  signature: request.headers["X-Hub-Signature-256"],
+  secret: ENV["WHATSAPP_APP_SECRET"]
+)
+messages = adapter_class.parse(JSON.parse(raw_body)) # => [InboundMessage]
+
+# Reply for one configured number
+adapter = adapter_class.new(phone_number_id: "123", access_token: "EAAG...")
+adapter.deliver(to: "254712345678", text: "Karibu! How can we help?")
+adapter.mark_read(message_id: "wamid....")
+```
+
 ## Key entry points
 
 - `Ask::ChannelProviders::Adapter` - base class for channel adapters.
   Implement `start(config:, &on_message)` (the callback receives
   `{ chat_id:, user_id:, text:, session_key: }`), `stop`, `send_message`,
   `edit_message`, `request_approval`, and `send_card`.
+- `Ask::ChannelProviders::WebhookAdapter` - base class for webhook-driven
+  channels: implement `.provider`, `.verify_signature`, `.parse`, and
+  `#deliver`; `.challenge` and `#mark_read` have safe defaults.
+- `Ask::ChannelProviders::InboundMessage` - the normalized inbound message
+  (`provider`, `external_uid`, `channel_id`, `message_id`, `kind`, `text`,
+  `name`, `timestamp`).
 - `Ask::ChannelProviders::Telegram::Adapter` - the Telegram implementation,
   backed by the polling-based `Telegram::Bot`. Config: `token`,
   `allowed_users`, `allowed_chats`.
+- `Ask::ChannelProviders::WhatsApp::Adapter` / `::Client` - the WhatsApp
+  Cloud API implementation (Meta Graph API, direct): webhook verification
+  and parsing, chunked text sends, read receipts.
 - `Ask::ChannelProviders::Card` - a structured UI element each adapter
   renders to its native format. Build cards with `section`, `text`,
   `button(label, callback:, url:)`, `table(header:, rows:)`, and `divider`.

data/lib/ask/channel_providers/inbound_message.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Ask
+  module ChannelProviders
+    # One inbound message, normalized across webhook channels. Adapters
+    # parse their provider's payload into these; everything downstream
+    # (routing, persistence, agents) works with this shape only.
+    #
+    # +channel_id+ identifies the receiving account on the provider (the
+    # WhatsApp phone number id, the Telegram bot id, ...); +external_uid+
+    # identifies the sender on the provider. +media_id+ and +media_type+
+    # carry the provider's handle for an attachment (image, voice note,
+    # document) so the consumer can download it.
+    class InboundMessage
+      ATTRIBUTES = %i[provider external_uid channel_id message_id kind text name timestamp media_id media_type].freeze
+
+      attr_reader(*ATTRIBUTES)
+
+      def initialize(provider:, external_uid:, channel_id:, message_id:, kind: "text", text: nil, name: nil, timestamp: nil, media_id: nil, media_type: nil)
+        @provider = provider
+        @external_uid = external_uid
+        @channel_id = channel_id
+        @message_id = message_id
+        @kind = kind
+        @text = text
+        @name = name
+        @timestamp = timestamp
+        @media_id = media_id
+        @media_type = media_type
+      end
+
+      def media?
+        !media_id.to_s.strip.empty?
+      end
+
+      def text?
+        kind.to_s == "text" && !text.to_s.strip.empty?
+      end
+
+      # JSON-safe for background-job serialization.
+      def to_h
+        ATTRIBUTES.to_h { |attribute| [attribute.to_s, public_send(attribute)] }
+      end
+
+      def self.from_h(hash)
+        attributes = hash.to_h.transform_keys(&:to_sym)
+        new(**ATTRIBUTES.to_h { |attribute| [attribute, attributes[attribute]] })
+      end
+    end
+  end
+end

data/lib/ask/channel_providers/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module ChannelProviders
-    VERSION = "0.1.1"
+    VERSION = "0.2.0"
   end
 end

data/lib/ask/channel_providers/webhook_adapter.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Ask
+  module ChannelProviders
+    # Base class for webhook-driven channels: the provider pushes messages
+    # to your HTTP endpoint, so there is no local polling loop to start.
+    #
+    # The inbound edge is class-level — signature verification and parsing
+    # run before any channel configuration is known, and the receiving
+    # account is resolved from the parsed payload. The outbound edge is
+    # instance-level, bound to one configured account.
+    #
+    # Subclasses implement .provider, .verify_signature, .parse, and
+    # #deliver; .challenge and #mark_read have safe defaults.
+    class WebhookAdapter < Adapter
+      # The provider slug ("whatsapp", "telegram", ...).
+      def self.provider
+        raise NotImplementedError, "#{name} must implement .provider"
+      end
+
+      # Verifies the provider's signature over the raw request body.
+      #
+      # @param raw_body [String] the unmodified request body
+      # @param signature [String] the provider's signature header value
+      # @param secret [String] the app secret shared with the provider
+      # @return [Boolean]
+      def self.verify_signature(raw_body:, signature:, secret:)
+        raise NotImplementedError, "#{name} must implement .verify_signature"
+      end
+
+      # Answers the provider's GET webhook-registration challenge.
+      #
+      # @param params [Hash] the request query parameters
+      # @param verify_token [String] the token configured with the provider
+      # @return [String, nil] the challenge to echo, or nil when invalid
+      def self.challenge(params, verify_token:)
+        nil
+      end
+
+      # Parses a webhook payload into messages.
+      #
+      # @param payload [Hash] the parsed JSON body
+      # @return [Array<InboundMessage>]
+      def self.parse(payload)
+        raise NotImplementedError, "#{name} must implement .parse"
+      end
+
+      # Webhook channels receive through their HTTP endpoint; there is no
+      # local loop. No-op keeps the uniform Adapter interface honest.
+      def start(config: {}, &on_message)
+        nil
+      end
+
+      def stop
+        nil
+      end
+
+      # Delivers a text reply to +to+ (the provider's user/chat id).
+      #
+      # @return [String, nil] the provider's message id
+      def deliver(to:, text:)
+        raise NotImplementedError, "#{self.class} must implement #deliver"
+      end
+
+      # Marks an inbound message as read where the provider supports it.
+      def mark_read(message_id:)
+        nil
+      end
+
+      # The uniform Adapter interface delegates to #deliver.
+      def send_message(chat_id, text)
+        deliver(to: chat_id, text: text)
+      end
+
+      # Most business messaging APIs cannot edit a sent message (WhatsApp
+      # cannot at all), so this stays unsupported rather than lying.
+      def edit_message(chat_id, message_id, text)
+        raise NotImplementedError, "#{self.class} does not support editing messages"
+      end
+    end
+  end
+end

data/lib/ask/channel_providers/whatsapp/adapter.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Ask
+  module ChannelProviders
+    module WhatsApp
+      # The WhatsApp Cloud API adapter: verifies Meta's X-Hub-Signature-256
+      # over the raw webhook body, parses payloads into InboundMessages, and
+      # delivers replies for one configured phone number.
+      #
+      # Secrets are passed in (never read from globals) so the same adapter
+      # serves many accounts in one process.
+      class Adapter < WebhookAdapter
+        SIGNATURE_PREFIX = "sha256="
+
+        class << self
+          def provider
+            "whatsapp"
+          end
+
+          # Meta signs every webhook POST with HMAC-SHA256 of the raw body,
+          # keyed by the Meta app secret: "sha256=<hex>".
+          def verify_signature(raw_body:, signature:, secret:)
+            return false if secret.to_s.empty? || signature.to_s.empty?
+
+            expected = "#{SIGNATURE_PREFIX}#{OpenSSL::HMAC.hexdigest("SHA256", secret, raw_body)}"
+            secure_compare(expected, signature.to_s)
+          end
+
+          # The GET challenge Meta sends when the webhook URL is registered.
+          def challenge(params, verify_token:)
+            return unless params["hub.mode"] == "subscribe"
+            return if verify_token.to_s.empty?
+            return unless secure_compare(params["hub.verify_token"].to_s, verify_token.to_s)
+
+            params["hub.challenge"]
+          end
+
+          def parse(payload)
+            Array(payload["entry"]).flat_map { |entry| Array(entry["changes"]) }.flat_map do |change|
+              value = change["value"] || {}
+              next [] unless value["messaging_product"] == "whatsapp"
+
+              metadata = value["metadata"] || {}
+              names = Array(value["contacts"]).to_h { |contact| [contact["wa_id"].to_s, contact] }
+              Array(value["messages"]).map { |raw| build_message(raw, metadata, names) }
+            end
+          end
+
+          def build_message(raw, metadata, names)
+            type = raw["type"].to_s
+            media = raw[type].is_a?(Hash) ? raw[type] : {}
+            InboundMessage.new(
+              provider: provider,
+              external_uid: raw["from"].to_s,
+              channel_id: metadata["phone_number_id"].to_s,
+              message_id: raw["id"].to_s,
+              kind: type,
+              text: (raw.dig("text", "body").to_s if type == "text"),
+              name: names.dig(raw["from"].to_s, "profile", "name"),
+              timestamp: raw["timestamp"].to_s,
+              media_id: media["id"],
+              media_type: media["mime_type"]
+            )
+          end
+
+          private
+
+          # Constant-time comparison without ActiveSupport.
+          def secure_compare(first, second)
+            return false unless first.bytesize == second.bytesize
+
+            left = first.unpack("C*")
+            right = second.unpack("C*")
+            right.each_with_index { |byte, index| left[index] ^= byte }
+            left.all?(&:zero?)
+          end
+        end
+
+        def initialize(phone_number_id:, access_token:, graph_version: nil, client: nil)
+          @client = client || Client.new(
+            phone_number_id: phone_number_id,
+            access_token: access_token,
+            graph_version: graph_version
+          )
+        end
+
+        def deliver(to:, text:)
+          @client.send_text(to: to, text: text)
+        end
+
+        def mark_read(message_id:)
+          @client.mark_read(message_id: message_id)
+        end
+
+        # Downloads an inbound attachment (image, voice note, document).
+        def media(media_id)
+          @client.fetch_media(media_id)
+        end
+      end
+    end
+  end
+end

data/lib/ask/channel_providers/whatsapp/client.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Ask
+  module ChannelProviders
+    module WhatsApp
+      # Sends text messages and read receipts through the Meta Graph API for
+      # one WhatsApp phone number. Long replies become several WhatsApp
+      # messages, split on paragraph/line boundaries so nothing is cut
+      # mid-word.
+      class Client
+        DEFAULT_GRAPH_VERSION = "v23.0"
+        BASE_URL = "https://graph.facebook.com"
+        MAX_TEXT_LENGTH = 4096
+
+        class << self
+          # The shared transport; swap in tests or for another HTTP stack.
+          attr_writer :transport
+
+          def transport
+            @transport ||= Transport.new
+          end
+        end
+
+        def initialize(phone_number_id:, access_token:, graph_version: nil, transport: nil)
+          @phone_number_id = phone_number_id
+          @access_token = access_token
+          @graph_version = graph_version.to_s.empty? ? DEFAULT_GRAPH_VERSION : graph_version
+          @transport = transport || self.class.transport
+        end
+
+        # Sends +text+ (splitting if needed).
+        #
+        # @return [String, nil] the last message id the provider returned
+        def send_text(to:, text:)
+          chunks(text).map do |chunk|
+            response = post("messages", {
+              messaging_product: "whatsapp",
+              to: to,
+              type: "text",
+              text: {body: chunk, preview_url: false}
+            })
+            response.dig("messages", 0, "id")
+          end.compact.last
+        end
+
+        def mark_read(message_id:)
+          post("messages", {
+            messaging_product: "whatsapp",
+            status: "read",
+            message_id: message_id
+          })
+        end
+
+        # Downloads an inbound attachment by its media handle: the Graph API
+        # answers a short-lived URL, which is fetched with the same bearer.
+        #
+        # @return [Hash] {body:, mime_type:} with the raw bytes
+        def fetch_media(media_id)
+          meta_response = @transport.get(
+            url: "#{BASE_URL}/#{@graph_version}/#{media_id}",
+            headers: {"Authorization" => "Bearer #{@access_token}"}
+          )
+          raise APIError, "graph api returned #{meta_response.status}: #{meta_response.body}" unless meta_response.success?
+
+          info = JSON.parse(meta_response.body)
+          file_response = @transport.get(url: info["url"], headers: {"Authorization" => "Bearer #{@access_token}"})
+          raise APIError, "media download returned #{file_response.status}" unless file_response.success?
+
+          {body: file_response.body, mime_type: info["mime_type"]}
+        rescue JSON::ParserError, SocketError, Timeout::Error, SystemCallError => e
+          raise APIError, e.message
+        end
+
+        # Splits a reply into WhatsApp-sized messages at the last paragraph,
+        # line, or word boundary before the limit.
+        def chunks(text)
+          remaining = text.to_s.strip
+          parts = []
+          while remaining.length > MAX_TEXT_LENGTH
+            boundary = remaining.rindex(/\n\n/, MAX_TEXT_LENGTH) ||
+              remaining.rindex("\n", MAX_TEXT_LENGTH) ||
+              remaining.rindex(" ", MAX_TEXT_LENGTH) ||
+              MAX_TEXT_LENGTH
+            parts << remaining[0...boundary].strip
+            remaining = remaining[boundary..].to_s.strip
+          end
+          parts << remaining unless remaining.empty?
+          parts
+        end
+
+        private
+
+        def post(path, body)
+          response = @transport.post(
+            url: "#{BASE_URL}/#{@graph_version}/#{@phone_number_id}/#{path}",
+            headers: {
+              "Authorization" => "Bearer #{@access_token}",
+              "Content-Type" => "application/json"
+            },
+            body: JSON.generate(body)
+          )
+          unless response.success?
+            raise APIError, "graph api returned #{response.status}: #{response.body}"
+          end
+
+          JSON.parse(response.body)
+        rescue JSON::ParserError, SocketError, Timeout::Error, SystemCallError => e
+          raise APIError, e.message
+        end
+      end
+    end
+  end
+end

data/lib/ask/channel_providers/whatsapp/transport.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Ask
+  module ChannelProviders
+    module WhatsApp
+      # The HTTP transport for Graph API calls. One small seam so tests (and
+      # alternate HTTP stacks) can swap the implementation.
+      class Transport
+        OPEN_TIMEOUT = 10
+        READ_TIMEOUT = 15
+
+        Response = Struct.new(:status, :body, keyword_init: true) do
+          def success?
+            (200..299).cover?(status)
+          end
+        end
+
+        def post(url:, headers:, body:)
+          uri = URI(url)
+          request = Net::HTTP::Post.new(uri)
+          headers.each { |key, value| request[key] = value }
+          request.body = body
+          perform(uri, request)
+        end
+
+        def get(url:, headers: {})
+          uri = URI(url)
+          request = Net::HTTP::Get.new(uri)
+          headers.each { |key, value| request[key] = value }
+          perform(uri, request)
+        end
+
+        private
+
+        def perform(uri, request)
+          response = Net::HTTP.start(
+            uri.host, uri.port,
+            use_ssl: uri.scheme == "https",
+            open_timeout: OPEN_TIMEOUT,
+            read_timeout: READ_TIMEOUT
+          ) { |http| http.request(request) }
+          Response.new(status: response.code.to_i, body: response.body.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/ask/channel_providers/whatsapp.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "whatsapp/transport"
+require_relative "whatsapp/client"
+require_relative "whatsapp/adapter"
+
+module Ask
+  module ChannelProviders
+    # WhatsApp Cloud API support (Meta's Graph API, direct — no BSP).
+    module WhatsApp
+    end
+  end
+end

data/lib/ask/channel_providers.rb

@@ -3,7 +3,10 @@
 require_relative "channel_providers/version"
 require_relative "channel_providers/card"
 require_relative "channel_providers/adapter"
+require_relative "channel_providers/inbound_message"
+require_relative "channel_providers/webhook_adapter"
 require_relative "channel_providers/telegram"
+require_relative "channel_providers/whatsapp"
 
 module Ask
   module ChannelProviders

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-channel-providers
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -94,10 +94,16 @@ files:
 - lib/ask/channel_providers.rb
 - lib/ask/channel_providers/adapter.rb
 - lib/ask/channel_providers/card.rb
+- lib/ask/channel_providers/inbound_message.rb
 - lib/ask/channel_providers/telegram.rb
 - lib/ask/channel_providers/telegram/adapter.rb
 - lib/ask/channel_providers/telegram/bot.rb
 - lib/ask/channel_providers/version.rb
+- lib/ask/channel_providers/webhook_adapter.rb
+- lib/ask/channel_providers/whatsapp.rb
+- lib/ask/channel_providers/whatsapp/adapter.rb
+- lib/ask/channel_providers/whatsapp/client.rb
+- lib/ask/channel_providers/whatsapp/transport.rb
 homepage: https://github.com/ask-rb/ask-channel-providers
 licenses:
 - MIT