arafa 0.1.0

data/lib/arafa/data/africas_talking.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require "dry/initializer"
+require "dry/monads"
+
+require_relative "../types"
+require_relative "../errors"
+require_relative "../phone_number"
+require_relative "../send_result"
+require_relative "../providers/base"
+require_relative "../contracts/mobile_data_contract"
+
+module Arafa
+  module Data
+    # Africa's Talking Mobile Data adapter (§1.12), AT-only — Wasiliana has no
+    # equivalent. Doesn't extend `Airtime::Base`/`Providers::Base`: each
+    # recipient carries its own `quantity`/`unit`/`validity`/`metadata`
+    # rather than one shape applied uniformly, so there's nothing to share.
+    # Still follows the same ctor/contract/HTTP/`Result` conventions, reusing
+    # `Providers::Base`'s Faraday connection.
+    class AfricasTalking
+      extend Dry::Initializer
+      include Dry::Monads[:result]
+
+      CONTRACT = Contracts::MobileDataContract
+
+      # Symbolizes recipient hash keys and normalizes `phone_number`
+      # (local/international -> `254...`) up front, so `#build_payload` and
+      # the contract both see a consistent shape.
+      RECIPIENTS_TYPE = Types::Array.of(Types::Hash).constructor do |value|
+        Array(value).map do |recipient|
+          normalized = recipient.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+          phone = normalized[:phone_number]
+          normalized[:phone_number] = Arafa::PhoneNumber.normalize(phone) if phone
+          normalized
+        end
+      end
+
+      option :product_name, type: Types::String
+      option :recipients, type: RECIPIENTS_TYPE
+      option :username, optional: true, type: Types::String.optional, default: -> { Arafa.config.africas_talking.username }
+      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://bundles.africastalking.com/mobile/data/request"
+      end
+
+      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, productName: product_name, recipients: recipients.map { |r| build_recipient_payload(r) } }
+      end
+
+      def parse_response(response)
+        return build_failure(response) unless response.status.between?(200, 299)
+
+        body = response.body
+        entries = Array(body["entries"])
+        return Failure(Arafa::InvalidRequestError.new(body["errorMessage"] || body.to_s)) if entries.empty?
+
+        build_success(body, entries)
+      end
+
+      private
+
+      def build_recipient_payload(recipient)
+        recipient.slice(:quantity, :unit, :validity, :metadata).merge(phoneNumber: recipient[:phone_number])
+      end
+
+      def build_success(body, entries)
+        recipients = entries.map { |e| build_recipient(e) }
+        Success(SendResult.new(provider: :mobile_data_africas_talking, recipients: recipients, raw: body))
+      end
+
+      def build_recipient(entry)
+        success = entry["status"] == "Queued"
+        SendResult::Recipient.new(
+          number: entry["phoneNumber"], success: success, message_id: entry["transactionId"],
+          status: entry["status"], cost: entry["value"], error: success ? nil : entry["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
+        body.is_a?(Hash) ? (body["errorMessage"] || body.to_s) : body.to_s
+      end
+
+      def validate_contract
+        result = self.class::CONTRACT.new.call(contract_params)
+        return Failure(Arafa::ValidationError.new(result.errors.to_h)) if result.failure?
+
+        Success(result)
+      end
+
+      def contract_params
+        keys = %i[phone_number quantity unit validity metadata]
+        { product_name: product_name, recipients: recipients.map { |r| r.slice(*keys) } }
+      end
+    end
+  end
+end
+
+Arafa.register(:mobile_data_africas_talking, Arafa::Data::AfricasTalking)

data/lib/arafa/errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Arafa
+  class Error < StandardError; end
+
+  # Payload failed a dry-schema/dry-validation check; no HTTP call was made.
+  class ValidationError < Error; end
+
+  # Provider rejected the request due to invalid/missing credentials (HTTP 401).
+  class AuthenticationError < Error; end
+
+  # Provider rejected the request as malformed (HTTP 400/403/406).
+  class InvalidRequestError < Error; end
+
+  # Provider throttled the request (HTTP 429).
+  class RateLimitError < Error; end
+
+  # Provider failed on its own end (HTTP 500/503).
+  class ProviderServerError < Error; end
+
+  # The request never reached the provider (connection/timeout failure).
+  class NetworkError < Error; end
+end

data/lib/arafa/message.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "dry/struct"
+
+require_relative "types"
+
+module Arafa
+  # Normalized outbound message description shared by every provider adapter's
+  # `#send`. Coercion/validation of `to`/`text`/`from` happens via the leaf
+  # types (`Types::MsisdnList`, `Types::MessageText`, `Types::SenderId`) the
+  # moment the struct is built.
+  class Message < Dry::Struct
+    attribute :to, Types::MsisdnList
+    attribute :text, Types::MessageText
+    attribute? :from, Types::SenderId.optional
+  end
+end

data/lib/arafa/phone_number.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Arafa
+  # Normalizes Kenyan MSISDNs into the `2547XXXXXXXX` / `2541XXXXXXXX` form
+  # that both provider APIs expect, accepting local (`07...`/`01...`),
+  # international with a leading `+` (`+254...`), and already-normalized
+  # (`254...`) input.
+  module PhoneNumber
+    LOCAL_FORMAT = /\A0(7|1)\d{8}\z/
+    INTERNATIONAL_FORMAT = /\A\+?254(7|1)\d{8}\z/
+
+    def self.normalize(value)
+      digits = value.to_s.strip
+
+      case digits
+      when LOCAL_FORMAT
+        "254#{digits[1..]}"
+      when INTERNATIONAL_FORMAT
+        digits.delete_prefix("+")
+      else
+        digits
+      end
+    end
+  end
+end

data/lib/arafa/providers/africas_talking.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../contracts/africas_talking_contract"
+
+module Arafa
+  # Africa's Talking Bulk SMS adapter (§1.1). A single HTTP 200 can still
+  # carry a mix of successful and failed recipients, so success/failure is
+  # read out of each entry's `statusCode` in `SMSMessageData.Recipients`,
+  # never assumed from the HTTP status alone.
+  class AfricasTalking < Providers::Base
+    CONTRACT = Contracts::AfricasTalkingContract
+
+    # 100 Processed, 101 Sent, 102 Queued.
+    SUCCESS_STATUS_CODES = [100, 101, 102].freeze
+
+    option :username, optional: true, type: Types::String.optional, default: -> { Arafa.config.africas_talking.username }
+    option :enqueue, optional: true, type: Types::Integer.optional, default: -> { nil }
+
+    def endpoint
+      if Arafa.config.africas_talking.sandbox
+        "https://api.sandbox.africastalking.com/version1/messaging"
+      else
+        "https://api.africastalking.com/version1/messaging/bulk"
+      end
+    end
+
+    def headers
+      {
+        "apiKey" => Arafa.config.africas_talking.api_key,
+        "Content-Type" => "application/json",
+        "Accept" => "application/json"
+      }
+    end
+
+    def build_payload
+      payload = {
+        username: username,
+        phoneNumbers: to,
+        message: text,
+        senderId: from
+      }
+      payload[:enqueue] = enqueue unless enqueue.nil?
+      payload
+    end
+
+    def parse_response(response)
+      return build_result(response.body) if response.status.between?(200, 299)
+
+      Failure(error_class_for(response.status).new(error_message(response)))
+    end
+
+    private
+
+    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 error_class_for(status)
+      ERROR_CLASSES_BY_STATUS.fetch(status, Arafa::InvalidRequestError)
+    end
+
+    def build_result(body)
+      recipients = Array(body.dig("SMSMessageData", "Recipients"))
+
+      return Failure(Arafa::InvalidRequestError.new(error_message_for_empty_recipients(body))) if recipients.empty?
+
+      Success(
+        SendResult.new(
+          provider: :africas_talking,
+          recipients: recipients.map { |entry| build_recipient(entry) },
+          raw: body
+        )
+      )
+    end
+
+    def build_recipient(entry)
+      success = SUCCESS_STATUS_CODES.include?(entry["statusCode"])
+
+      SendResult::Recipient.new(
+        number: entry["number"],
+        success: success,
+        message_id: entry["messageId"],
+        status: entry["status"],
+        cost: entry["cost"],
+        error: success ? nil : entry["status"]
+      )
+    end
+
+    def error_message(response)
+      body = response.body
+      return body.to_s unless body.is_a?(Hash)
+
+      body["errorMessage"] || body.dig("SMSMessageData", "Message") || body.to_s
+    end
+
+    # AT can return HTTP 2xx with an empty `Recipients` array (e.g. sandbox
+    # routing rejects the number before it reaches SendResult's min_size: 1
+    # invariant) — fall back to `SMSMessageData.Message` for why.
+    def error_message_for_empty_recipients(body)
+      return body.to_s unless body.is_a?(Hash)
+
+      body.dig("SMSMessageData", "Message") || body.to_s
+    end
+  end
+end
+
+Arafa.register(:africas_talking, Arafa::AfricasTalking)

data/lib/arafa/providers/base.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "dry/initializer"
+require "dry/monads"
+require "faraday"
+require "faraday/retry"
+
+require_relative "../types"
+require_relative "../errors"
+require_relative "../version"
+
+module Arafa
+  module Providers
+    # Abstract superclass for provider adapters (`AfricasTalking`, `Wasiliana`, ...).
+    #
+    # Subclasses implement `#endpoint`, `#headers`, `#build_payload`, `#parse_response`,
+    # and set a `CONTRACT` constant (a `Dry::Validation::Contract`) applied to `to:`/
+    # `text:`/`from:` before any HTTP call is made.
+    class Base
+      extend Dry::Initializer
+      include Dry::Monads[:result]
+
+      # Wraps a scalar `to:` into an Array before per-element PhoneNumber coercion,
+      # so callers can pass either a single number or a list.
+      TO_TYPE = Types::Array.of(Types::PhoneNumber).constructor { |value| Array(value) }
+
+      option :text, type: Types::MessageText
+      option :to, type: TO_TYPE
+      option :from, optional: true, type: Types::SenderId.optional, default: -> { Arafa.config.default_sender }
+
+      class << self
+        # Accepts either provider keywords (`text:`, `to:`, `from:`) or a single
+        # positional object responding to `#to_arafa` (duck-typed message support).
+        def new(*args, **kwargs)
+          if args.size == 1 && args.first.respond_to?(:to_arafa)
+            kwargs = args.first.to_arafa.merge(kwargs)
+            args = []
+          end
+
+          super(*args, **kwargs)
+        end
+
+        # Shortcut for `new(**kwargs).send`. Falls back to `Kernel#send`'s
+        # dynamic-dispatch behavior for any other call shape (positional
+        # method-name args), since dry-initializer and friends rely on
+        # `klass.send(:some_method, ...)` internally.
+        def send(*args, **kwargs)
+          return super if args.any? || kwargs.empty?
+
+          new(**kwargs).send
+        end
+
+        def connection
+          @connection ||= build_connection
+        end
+
+        private
+
+        def build_connection
+          Faraday.new do |f|
+            f.request :json
+            f.response :json, content_type: /\bjson$/
+            f.request :retry, retry_statuses: [429, 500, 502, 503, 504]
+            f.response :logger, Arafa.logger, headers: true do |logger|
+              logger.filter(/(apiKey["']?\s*[:=]\s*["']?)([^"'&\s]+)/i, '\1[FILTERED]')
+            end
+            f.headers["User-Agent"] = "arafa/#{Arafa::VERSION}"
+            f.adapter Faraday.default_adapter
+          end
+        end
+      end
+
+      # Contract → HTTP call → response parsing. Returns a `Dry::Monads::Result`:
+      # `Success(SendResult)` or `Failure(Arafa::Error subclass)`. Falls back to
+      # `Kernel#send`'s dynamic-dispatch behavior if called with arguments.
+      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
+        raise NotImplementedError, "#{self.class} must implement #endpoint"
+      end
+
+      def headers
+        raise NotImplementedError, "#{self.class} must implement #headers"
+      end
+
+      def build_payload
+        raise NotImplementedError, "#{self.class} must implement #build_payload"
+      end
+
+      def parse_response(_response)
+        raise NotImplementedError, "#{self.class} must implement #parse_response"
+      end
+
+      private
+
+      def validate_contract
+        result = self.class::CONTRACT.new.call(to: to, text: text, from: from)
+        return Failure(Arafa::ValidationError.new(result.errors.to_h)) if result.failure?
+
+        Success(result)
+      end
+    end
+  end
+end

data/lib/arafa/providers/wasiliana.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../contracts/wasiliana_contract"
+
+module Arafa
+  # Wasiliana SMS send adapter (§1.4). Unlike Africa's Talking, Wasiliana's
+  # response carries no per-recipient breakdown — just an overall
+  # `status`/`data` pair — so success/failure is decided once for the whole
+  # request rather than per number.
+  class Wasiliana < Providers::Base
+    CONTRACT = Contracts::WasilianaContract
+
+    option :linkid, optional: true, type: Types::String.optional, default: -> { nil }
+    option :message_uid, optional: true, type: Types::String.optional, default: -> { nil }
+    option :is_otp, optional: true, type: Types::Any.optional, default: -> { nil }
+
+    def endpoint
+      "https://api.wasiliana.com/api/v1/send/sms"
+    end
+
+    def headers
+      {
+        "Content-Type" => "application/json",
+        "apiKey" => Arafa.config.wasiliana.api_key
+      }
+    end
+
+    def build_payload
+      payload = {
+        recipients: to,
+        from: from,
+        message: text
+      }
+      payload[:linkid] = linkid unless linkid.nil?
+      payload[:message_uid] = message_uid unless message_uid.nil?
+      payload[:is_otp] = is_otp unless is_otp.nil?
+      payload
+    end
+
+    def parse_response(response)
+      body = response.body
+
+      if response.status.between?(200, 299) && body.is_a?(Hash) && body["status"] == "success"
+        build_success(body)
+      else
+        build_failure(response)
+      end
+    end
+
+    private
+
+    def build_success(body)
+      Success(
+        SendResult.new(
+          provider: :wasiliana,
+          recipients: to.map { |number| build_recipient(number, body) },
+          raw: body
+        )
+      )
+    end
+
+    def build_recipient(number, body)
+      SendResult::Recipient.new(
+        number: number,
+        success: true,
+        message_id: message_uid,
+        status: body["data"]
+      )
+    end
+
+    ERROR_CLASSES_BY_STATUS = {
+      401 => Arafa::AuthenticationError,
+      400 => Arafa::InvalidRequestError,
+      403 => Arafa::InvalidRequestError,
+      404 => Arafa::InvalidRequestError,
+      405 => Arafa::InvalidRequestError,
+      406 => Arafa::InvalidRequestError,
+      429 => Arafa::RateLimitError,
+      500 => 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["message"] || body["error"] || body["data"] || body.to_s
+    end
+  end
+end
+
+Arafa.register(:wasiliana, Arafa::Wasiliana)

data/lib/arafa/schemas/airtime_request_schema.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "dry/schema"
+require "dry/types"
+
+module Arafa
+  module Schemas
+    # Leaf types used only for structural coercion within `Schemas::*`.
+    module Types
+      include Dry.Types()
+
+      # Wasiliana's docs show `phone_number` array-wrapped but the field also
+      # appears sent as a bare string — accept either and normalize to an array.
+      PhoneNumberList = (Types::Array.of(Types::String) |
+                          Types::String.constructor { |value| [value] })
+                        .constrained(min_size: 1)
+    end
+
+    # Wasiliana airtime request params.
+    AirtimeRequestSchema = Dry::Schema.JSON do
+      required(:phone_number).value(Schemas::Types::PhoneNumberList)
+      required(:currency_code).filled(:string)
+      required(:amount).filled(:string)
+      required(:callback).filled(:string)
+      optional(:airtime_uid).filled(:string)
+    end
+  end
+end

data/lib/arafa/schemas/delivery_report_schema.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "dry/schema"
+
+module Arafa
+  module Schemas
+    # Wasiliana delivery-report callback body, e.g.:
+    # {"phone": ["25472xxxxxxx"], "correlator": "message_...", "deliveryStatus": "0"}
+    DeliveryReportSchema = Dry::Schema.JSON do
+      required(:phone).array(:string)
+      required(:correlator).filled(:string)
+      required(:deliveryStatus).filled(:string)
+    end
+  end
+end

data/lib/arafa/schemas/ussd_callback_schema.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "dry/schema"
+
+module Arafa
+  module Schemas
+    # Shared shape for inbound USSD webhook params, after each provider's
+    # `Ussd::<Provider>.parse` remaps its own callback keys onto this
+    # canonical set (session_id, phone_number, service_code, text).
+    UssdCallbackSchema = Dry::Schema.Params do
+      required(:session_id).filled(:string)
+      required(:phone_number).filled(:string)
+      required(:service_code).filled(:string)
+      required(:text).maybe(:string)
+    end
+  end
+end

data/lib/arafa/send_result.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "dry/struct"
+
+require_relative "types"
+
+module Arafa
+  # Normalized outcome of a provider `#send` call. Wraps the per-recipient
+  # success/failure detail returned by both AT and Wasiliana into one shape,
+  # since a single HTTP 200 response (AT bulk SMS/airtime) can carry a mix of
+  # successful and failed recipients that must be surfaced individually
+  # rather than collapsed into one overall success flag.
+  class SendResult < Dry::Struct
+    # Per-recipient outcome, normalized from AT's numeric `statusCode` /
+    # Wasiliana's generic `status` string.
+    class Recipient < Dry::Struct
+      attribute :number, Types::PhoneNumber
+      attribute :success, Types::Bool
+      attribute? :message_id, Types::String.optional.default(nil)
+      attribute? :status, Types::String.optional.default(nil)
+      attribute? :cost, Types::String.optional.default(nil)
+      attribute? :error, Types::String.optional.default(nil)
+    end
+
+    attribute :provider, Types::Symbol
+    attribute :recipients, Types::Array.of(Recipient).constrained(min_size: 1)
+    attribute? :raw, Types::Any.optional.default(nil)
+
+    def success?
+      recipients.all?(&:success)
+    end
+
+    def message_id
+      recipients.first&.message_id
+    end
+  end
+end

data/lib/arafa/types.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "dry/types"
+
+require_relative "phone_number"
+
+module Arafa
+  # Leaf value types (coercion + constraints) shared across providers.
+  module Types
+    include Dry.Types()
+
+    PhoneNumber = Types::String
+                  .constructor { |value| Arafa::PhoneNumber.normalize(value) }
+                  .constrained(format: /\A254(7|1)\d{8}\z/)
+
+    MsisdnList = Types::Array.of(PhoneNumber).constrained(min_size: 1)
+
+    SenderId = Types::String.constrained(min_size: 1, max_size: 11)
+    MessageText = Types::String.constrained(min_size: 1, max_size: 918)
+  end
+end