arafa 0.1.0

data/lib/arafa/ussd/africas_talking.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "../schemas/ussd_callback_schema"
+
+module Arafa
+  module Ussd
+    # Parses Africa's Talking' form-encoded USSD callback params (`sessionId`,
+    # `phoneNumber`, `serviceCode`, `text`, `networkCode`) into the shared
+    # `Schemas::UssdCallbackSchema` shape. `networkCode` has no equivalent in
+    # the canonical shape and is dropped.
+    module AfricasTalking
+      module_function
+
+      def parse(params)
+        params = params.transform_keys(&:to_s)
+
+        Schemas::UssdCallbackSchema.call(
+          session_id: params["sessionId"],
+          phone_number: params["phoneNumber"],
+          service_code: params["serviceCode"],
+          text: params["text"]
+        )
+      end
+    end
+  end
+end

data/lib/arafa/ussd/request.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "dry/struct"
+
+require_relative "../types"
+require_relative "../errors"
+require_relative "africas_talking"
+require_relative "wasiliana"
+
+module Arafa
+  module Ussd
+    # Normalized inbound USSD request, built after a provider's raw webhook
+    # callback params have been remapped onto the shared
+    # `Schemas::UssdCallbackSchema` keys and validated. Parse/build only —
+    # no outbound HTTP call.
+    class Request < Dry::Struct
+      attribute :session_id, Types::String
+      attribute :phone_number, Types::String
+      attribute :service_code, Types::String
+      attribute :text, Types::String.optional
+
+      class << self
+        def from_africas_talking(params)
+          build(Ussd::AfricasTalking.parse(params))
+        end
+
+        def from_wasiliana(params)
+          build(Ussd::Wasiliana.parse(params))
+        end
+
+        private
+
+        def build(result)
+          raise Arafa::ValidationError, result.errors.to_h if result.failure?
+
+          new(**result.to_h)
+        end
+      end
+    end
+  end
+end

data/lib/arafa/ussd/response.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Arafa
+  module Ussd
+    # Builds the `CON `/`END `-prefixed plain-text reply body both providers'
+    # USSD callback contract expects within the 10-second response window
+    # (§1.2, §1.5). Not a network client — the adapter's own web framework is
+    # responsible for actually returning this body with `Content-Type:
+    # text/plain`.
+    module Response
+      module_function
+
+      # Session continues; the gateway will prompt the subscriber again and
+      # POST their next input as a new callback.
+      def continue(text)
+        "CON #{text}"
+      end
+
+      # Session terminates; this is the final screen shown to the subscriber.
+      def end(text)
+        "END #{text}"
+      end
+    end
+  end
+end

data/lib/arafa/ussd/wasiliana.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "../schemas/ussd_callback_schema"
+
+module Arafa
+  module Ussd
+    # Parses Wasiliana's JSON USSD callback params (`sessionId`,
+    # `phoneNumber`, `serviceCode`, `text`, `ussdId`) into the shared
+    # `Schemas::UssdCallbackSchema` shape. `ussdId` has no equivalent in the
+    # canonical shape and is dropped.
+    module Wasiliana
+      module_function
+
+      def parse(params)
+        params = params.transform_keys(&:to_s)
+
+        Schemas::UssdCallbackSchema.call(
+          session_id: params["sessionId"],
+          phone_number: params["phoneNumber"],
+          service_code: params["serviceCode"],
+          text: params["text"]
+        )
+      end
+    end
+  end
+end

data/lib/arafa/version.rb

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

data/lib/arafa/whatsapp/africas_talking.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require "dry/initializer"
+require "dry/monads"
+require "dry/validation"
+
+require_relative "../types"
+require_relative "../errors"
+require_relative "../send_result"
+require_relative "../providers/base"
+require_relative "message_body"
+
+module Arafa
+  module Contracts
+    # Structural + business rules for an outgoing WhatsApp send (§1.13).
+    # `body`'s own shape is already validated by `Whatsapp::MessageBody`
+    # (a `Dry::Struct` raises on construction), so this only covers the
+    # envelope fields shared by every message kind.
+    class WhatsappContract < Dry::Validation::Contract
+      option :username, default: -> { Arafa.config.africas_talking.username }
+      option :wa_number, default: -> { Arafa.config.africas_talking.wa_number }
+
+      params do
+        required(:phone_number).filled(:string)
+      end
+
+      rule do
+        base.failure("Africa's Talking username is not configured") if username.to_s.empty?
+        base.failure("Africa's Talking WhatsApp number is not configured") if wa_number.to_s.empty?
+      end
+    end
+  end
+
+  module Whatsapp
+    # Africa's Talking WhatsApp adapter (§1.13). Unlike bulk SMS/airtime/
+    # mobile data, AT's WhatsApp API sends to one recipient per request
+    # (`phoneNumber` is a single string, not an array), so `SendResult` here
+    # always carries exactly one recipient. All five documented message
+    # kinds are supported — see `Whatsapp::MessageBody`.
+    class AfricasTalking
+      extend Dry::Initializer
+      include Dry::Monads[:result]
+
+      CONTRACT = Contracts::WhatsappContract
+      BODY_TYPE = Types.Instance(MessageBody::Text) | Types.Instance(MessageBody::Media) |
+                  Types.Instance(MessageBody::Template) | Types.Instance(MessageBody::Interactive::Buttons) |
+                  Types.Instance(MessageBody::Interactive::List)
+
+      option :phone_number, type: Types::PhoneNumber
+      option :body, type: BODY_TYPE
+      option :username, optional: true, type: Types::String.optional, default: -> { Arafa.config.africas_talking.username }
+      option :wa_number, optional: true, type: Types::String.optional, default: -> { Arafa.config.africas_talking.wa_number }
+      option :idempotency_key, optional: true, type: Types::String.optional, default: -> { nil }
+
+      class << self
+        def send(*args, **kwargs)
+          return super if args.any? || kwargs.empty?
+
+          new(**kwargs).send
+        end
+
+        # Reuses `Providers::Base`'s connection (retry, JSON, apiKey-redacting
+        # logger) rather than building a second one.
+        def connection
+          Providers::Base.connection
+        end
+      end
+
+      # Contract → HTTP call → response parsing. Returns a
+      # `Dry::Monads::Result`: `Success(SendResult)` or
+      # `Failure(Arafa::Error subclass)`.
+      def send(*args, **kwargs)
+        return super if args.any? || kwargs.any?
+
+        validation = validate_contract
+        return validation if validation.failure?
+
+        response = connection.post(endpoint, build_payload, headers)
+        parse_response(response)
+      rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+        Failure(Arafa::NetworkError.new(e.message))
+      end
+
+      def connection
+        self.class.connection
+      end
+
+      def endpoint
+        "https://chat.africastalking.com/whatsapp/message/send"
+      end
+
+      # AT's WhatsApp API is the one product that spells this header
+      # lowercase (`apikey`) instead of `apiKey`.
+      def headers
+        base = {
+          "apikey" => Arafa.config.africas_talking.api_key,
+          "Content-Type" => "application/json",
+          "Accept" => "application/json"
+        }
+        idempotency_key.nil? ? base : base.merge("Idempotency-Key" => idempotency_key)
+      end
+
+      def build_payload
+        { username: username, waNumber: wa_number, phoneNumber: phone_number, body: body.to_h }
+      end
+
+      def parse_response(response)
+        return build_failure(response) unless response.status.between?(200, 299)
+
+        body = response.body
+        status = body["status"]
+        return Failure(Arafa::InvalidRequestError.new(body["errorMessage"] || body.to_s)) if status.nil?
+
+        build_success(body, status)
+      end
+
+      private
+
+      def build_success(body, status)
+        recipients = [build_recipient(body, status)]
+        Success(SendResult.new(provider: :whatsapp_africas_talking, recipients: recipients, raw: body))
+      end
+
+      def build_recipient(body, status)
+        success = status != "FAILED"
+
+        SendResult::Recipient.new(
+          number: body["phoneNumber"] || phone_number,
+          success: success,
+          message_id: body["messageId"],
+          status: status,
+          error: success ? nil : (body["errorMessage"] || status)
+        )
+      end
+
+      ERROR_CLASSES_BY_STATUS = {
+        401 => Arafa::AuthenticationError,
+        400 => Arafa::InvalidRequestError,
+        403 => Arafa::InvalidRequestError,
+        406 => Arafa::InvalidRequestError,
+        429 => Arafa::RateLimitError,
+        500 => Arafa::ProviderServerError,
+        501 => Arafa::ProviderServerError,
+        502 => Arafa::ProviderServerError,
+        503 => Arafa::ProviderServerError
+      }.freeze
+
+      def build_failure(response)
+        error_class = ERROR_CLASSES_BY_STATUS.fetch(response.status, Arafa::InvalidRequestError)
+        Failure(error_class.new(error_message(response)))
+      end
+
+      def error_message(response)
+        body = response.body
+        return body.to_s unless body.is_a?(Hash)
+
+        body["errorMessage"] || body.to_s
+      end
+
+      def validate_contract
+        result = self.class::CONTRACT.new(username: username, wa_number: wa_number).call(contract_params)
+        return Failure(Arafa::ValidationError.new(result.errors.to_h)) if result.failure?
+
+        Success(result)
+      end
+
+      def contract_params
+        { phone_number: phone_number }
+      end
+    end
+  end
+end
+
+Arafa.register(:whatsapp_africas_talking, Arafa::Whatsapp::AfricasTalking)

data/lib/arafa/whatsapp/message_body.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "dry/struct"
+
+require_relative "../types"
+
+module Arafa
+  module Whatsapp
+    # Sum type over WhatsApp's polymorphic `body` field (§1.13). Each message
+    # kind gets its own `Dry::Struct` (coerced/validated the moment it's
+    # built) instead of one contract with every field across every kind
+    # marked optional — `Whatsapp::AfricasTalking#body` accepts any of these
+    # and calls `#to_h` to get the wire shape.
+    module MessageBody
+      # Plain-text WhatsApp message body: `{message}`.
+      class Text < Dry::Struct
+        attribute :message, Types::String.constrained(min_size: 1)
+
+        def to_h
+          { message: message }
+        end
+      end
+
+      # Media WhatsApp message body: `{mediaType, url, caption}`.
+      class Media < Dry::Struct
+        MEDIA_TYPES = %w[Image Video Audio Sticker Document Voice].freeze
+
+        attribute :media_type, Types::String.enum(*MEDIA_TYPES)
+        attribute :url, Types::String.constrained(min_size: 1)
+        attribute? :caption, Types::String.optional.default(nil)
+
+        def to_h
+          body = { mediaType: media_type, url: url }
+          body[:caption] = caption unless caption.nil?
+          body
+        end
+      end
+
+      # Template WhatsApp message body: `{templateId, headerValue, bodyValues}`.
+      class Template < Dry::Struct
+        attribute :template_id, Types::String.constrained(min_size: 1)
+        attribute :body_values, Types::Array.of(Types::String)
+        attribute? :header_value, Types::String.optional.default(nil)
+
+        def to_h
+          body = { templateId: template_id, bodyValues: body_values }
+          body[:headerValue] = header_value unless header_value.nil?
+          body
+        end
+      end
+
+      # Nested types shared by the two interactive message kinds.
+      module Interactive
+        # One tappable button: `{id, title}`.
+        class Button < Dry::Struct
+          attribute :id, Types::String.constrained(min_size: 1)
+          attribute :title, Types::String.constrained(min_size: 1)
+
+          def to_h
+            { id: id, title: title }
+          end
+        end
+
+        # One row of an interactive list section: `{id, title, description}`.
+        class Row < Dry::Struct
+          attribute :id, Types::String.constrained(min_size: 1)
+          attribute :title, Types::String.constrained(min_size: 1)
+          attribute? :description, Types::String.optional.default(nil)
+
+          def to_h
+            body = { id: id, title: title }
+            body[:description] = description unless description.nil?
+            body
+          end
+        end
+
+        # One section of an interactive list: `{title, rows, product_items}`.
+        class Section < Dry::Struct
+          attribute :title, Types::String.constrained(min_size: 1)
+          attribute :rows, Types::Array.of(Row)
+          attribute? :product_items, Types::Array.optional.default(nil)
+
+          def to_h
+            body = { title: title, rows: rows.map(&:to_h) }
+            body[:product_items] = product_items unless product_items.nil?
+            body
+          end
+        end
+
+        # Interactive buttons WhatsApp message body:
+        # `{action: {buttons}, body: {text}, header: {text}}`.
+        class Buttons < Dry::Struct
+          attribute :buttons, Types::Array.of(Button)
+          attribute :body_text, Types::String.constrained(min_size: 1)
+          attribute? :header_text, Types::String.optional.default(nil)
+
+          def to_h
+            body = { action: { buttons: buttons.map(&:to_h) }, body: { text: body_text } }
+            body[:header] = { text: header_text } unless header_text.nil?
+            body
+          end
+        end
+
+        # Interactive list WhatsApp message body:
+        # `{action: {button, sections}, body: {text}, header: {text}, footer: {text}}`.
+        class List < Dry::Struct
+          attribute :button, Types::String.constrained(min_size: 1)
+          attribute :sections, Types::Array.of(Section)
+          attribute :body_text, Types::String.constrained(min_size: 1)
+          attribute? :header_text, Types::String.optional.default(nil)
+          attribute? :footer_text, Types::String.optional.default(nil)
+
+          def to_h
+            body = { action: { button: button, sections: sections.map(&:to_h) }, body: { text: body_text } }
+            body[:header] = { text: header_text } unless header_text.nil?
+            body[:footer] = { text: footer_text } unless footer_text.nil?
+            body
+          end
+        end
+      end
+
+      class << self
+        def text(message:)
+          Text.new(message: message)
+        end
+
+        def media(media_type:, url:, caption: nil)
+          Media.new(media_type: media_type, url: url, caption: caption)
+        end
+
+        def template(template_id:, body_values:, header_value: nil)
+          Template.new(template_id: template_id, body_values: body_values, header_value: header_value)
+        end
+
+        def interactive_buttons(buttons:, body_text:, header_text: nil)
+          Interactive::Buttons.new(buttons: buttons, body_text: body_text, header_text: header_text)
+        end
+
+        def interactive_list(button:, sections:, body_text:, header_text: nil, footer_text: nil)
+          Interactive::List.new(button: button, sections: sections, body_text: body_text,
+                                header_text: header_text, footer_text: footer_text)
+        end
+      end
+    end
+  end
+end

data/lib/arafa.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "arafa/version"
+require_relative "arafa/errors"
+require_relative "arafa/phone_number"
+require_relative "arafa/types"
+require_relative "arafa/message"
+require_relative "arafa/send_result"
+require_relative "arafa/configuration"
+require_relative "arafa/contracts/base_contract"
+require_relative "arafa/contracts/africas_talking_contract"
+require_relative "arafa/contracts/wasiliana_contract"
+require_relative "arafa/contracts/airtime_contract"
+require_relative "arafa/contracts/africas_talking_airtime_contract"
+require_relative "arafa/contracts/mobile_data_contract"
+require_relative "arafa/schemas/ussd_callback_schema"
+require_relative "arafa/schemas/delivery_report_schema"
+require_relative "arafa/schemas/airtime_request_schema"
+require_relative "arafa/providers/base"
+require_relative "arafa/airtime/base"
+require_relative "arafa/ussd/africas_talking"
+require_relative "arafa/ussd/wasiliana"
+require_relative "arafa/ussd/response"
+require_relative "arafa/ussd/request"
+
+# A single, uniform interface to Kenyan SMS/USSD/Airtime gateways.
+module Arafa
+  class << self
+    def configure(&block)
+      Configuration.configure(&block)
+    end
+
+    def config
+      Configuration.config
+    end
+
+    def logger
+      config.logger
+    end
+
+    # Registers a provider class under a name so it can be dispatched to at
+    # runtime, e.g. `Arafa.register(:wasiliana, Arafa::Wasiliana)`.
+    def register(name, klass)
+      registry[name.to_sym] = klass
+    end
+
+    # Dispatches to a registered provider by name, e.g.
+    # `Arafa.send(:wasiliana, text: "Hello", to: "0712345678")`.
+    def send(name, **kwargs)
+      provider = registry.fetch(name.to_sym) { raise ArgumentError, "unknown provider: #{name.inspect}" }
+      provider.send(**kwargs)
+    end
+
+    private
+
+    def registry
+      @registry ||= {}
+    end
+  end
+end
+
+require_relative "arafa/providers/africas_talking"
+require_relative "arafa/providers/wasiliana"
+require_relative "arafa/airtime/wasiliana"
+require_relative "arafa/airtime/africas_talking"
+require_relative "arafa/data/africas_talking"
+require_relative "arafa/whatsapp/message_body"
+require_relative "arafa/whatsapp/africas_talking"

data/sig/arafa.rbs

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