arafa 0.1.0

data/lib/arafa/airtime/africas_talking.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../contracts/africas_talking_airtime_contract"
+
+module Arafa
+  module Airtime
+    # Africa's Talking airtime request adapter (§1.10). A single HTTP 200 can
+    # still carry a mix of Sent/Failed recipients (read from `responses`), or
+    # reject the whole request via a top-level `errorMessage` with no
+    # `responses` at all (e.g. an unconfigured/invalid username) — both cases
+    # are handled, unlike the AT SMS adapter which only needs the former.
+    class AfricasTalking < Airtime::Base
+      CONTRACT = Contracts::AfricasTalkingAirtimeContract
+
+      option :username, optional: true, type: Types::String.optional, default: -> { Arafa.config.africas_talking.username }
+      option :max_num_retry, optional: true, type: Types::Integer.optional, default: -> { nil }
+      option :request_metadata, optional: true, type: Types::Hash.optional, default: -> { nil }
+      option :idempotency_key, optional: true, type: Types::String.optional, default: -> { nil }
+
+      def endpoint
+        "https://api.africastalking.com/version1/airtime/send"
+      end
+
+      def headers
+        headers = {
+          "apiKey" => Arafa.config.africas_talking.api_key,
+          "Content-Type" => "application/json",
+          "Accept" => "application/json"
+        }
+        headers["Idempotency-Key"] = idempotency_key unless idempotency_key.nil?
+        headers
+      end
+
+      def build_payload
+        payload = {
+          username: username,
+          recipients: phone_number.map { |number| { phoneNumber: number, amount: "#{currency_code} #{amount}" } }
+        }
+        payload[:maxNumRetry] = max_num_retry unless max_num_retry.nil?
+        payload[:requestMetadata] = request_metadata unless request_metadata.nil?
+        payload
+      end
+
+      def parse_response(response)
+        return build_failure(response) unless response.status.between?(200, 299)
+
+        body = response.body
+        entries = Array(body["responses"])
+        return Failure(Arafa::InvalidRequestError.new(body["errorMessage"] || body.to_s)) if entries.empty?
+
+        build_success(body, entries)
+      end
+
+      private
+
+      def build_success(body, entries)
+        Success(
+          SendResult.new(
+            provider: :airtime_africas_talking,
+            recipients: entries.map { |entry| build_recipient(entry) },
+            raw: body
+          )
+        )
+      end
+
+      def build_recipient(entry)
+        success = entry["status"] == "Sent"
+
+        SendResult::Recipient.new(
+          number: entry["phoneNumber"],
+          success: success,
+          message_id: entry["requestId"],
+          status: entry["status"],
+          cost: entry["amount"],
+          error: success ? nil : entry["errorMessage"]
+        )
+      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
+    end
+  end
+end
+
+Arafa.register(:airtime_africas_talking, Arafa::Airtime::AfricasTalking)

data/lib/arafa/airtime/base.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "dry/initializer"
+require "dry/monads"
+
+require_relative "../types"
+require_relative "../errors"
+require_relative "../providers/base"
+
+module Arafa
+  module Airtime
+    # Abstract superclass for airtime adapters (`Airtime::Wasiliana`,
+    # `Airtime::AfricasTalking`). Mirrors `Providers::Base`'s pattern
+    # (contract-then-HTTP-call `#send`, shared Faraday connection) but with
+    # an airtime-shaped payload: `phone_number`/`currency_code`/`amount`
+    # applied to every recipient in the batch, rather than `to`/`text`/`from`.
+    #
+    # Subclasses implement `#endpoint`, `#headers`, `#build_payload`, and
+    # `#parse_response`, and set a `CONTRACT` constant (a
+    # `Dry::Validation::Contract`, built on `Contracts::AirtimeContract`).
+    class Base
+      extend Dry::Initializer
+      include Dry::Monads[:result]
+
+      # Wraps a scalar `phone_number:` into an Array before per-element
+      # PhoneNumber coercion, same as `Providers::Base::TO_TYPE`.
+      PHONE_NUMBER_TYPE = Types::Array.of(Types::PhoneNumber).constructor { |value| Array(value) }
+
+      option :phone_number, type: PHONE_NUMBER_TYPE
+      option :currency_code, type: Types::String
+      option :amount, type: Types::Any
+      option :callback, optional: true, type: Types::String.optional, default: -> { nil }
+      option :airtime_uid, optional: true, type: Types::String.optional, default: -> { nil }
+
+      class << self
+        # Shortcut for `new(**kwargs).send`, matching `Providers::Base.send`.
+        def send(*args, **kwargs)
+          return super if args.any? || kwargs.empty?
+
+          new(**kwargs).send
+        end
+
+        # Reuses `Providers::Base`'s Faraday connection (retry, JSON, logger
+        # with apiKey redaction) 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
+        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
+
+      # Omits `callback`/`airtime_uid` entirely when nil rather than passing
+      # them through as explicit nils — dry-schema's `optional(...).filled`
+      # treats a present-but-nil key as "must be filled" rather than
+      # "is missing", which would wrongly fail contracts where these fields
+      # are genuinely optional (e.g. AT's airtime_uid, or callback for AT).
+      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
+        params = { phone_number: phone_number, currency_code: currency_code, amount: amount }
+        params[:callback] = callback unless callback.nil?
+        params[:airtime_uid] = airtime_uid unless airtime_uid.nil?
+        params
+      end
+    end
+  end
+end

data/lib/arafa/airtime/wasiliana.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../contracts/airtime_contract"
+
+module Arafa
+  module Airtime
+    # Wasiliana airtime request adapter (§1.6). Like Wasiliana's SMS adapter,
+    # the response carries no per-recipient breakdown — just an overall
+    # `status`/`message` pair — so success/failure is decided once for the
+    # whole request rather than per phone number.
+    class Wasiliana < Airtime::Base
+      CONTRACT = Contracts::AirtimeContract
+
+      def endpoint
+        "https://api.wasiliana.com/api/v1/airtime/request"
+      end
+
+      def headers
+        {
+          "Content-Type" => "application/json",
+          "apiKey" => Arafa.config.wasiliana.api_key
+        }
+      end
+
+      def build_payload
+        payload = {
+          phone_number: phone_number,
+          currency_code: currency_code,
+          amount: amount,
+          callback: callback
+        }
+        payload[:airtime_uid] = airtime_uid unless airtime_uid.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: :airtime_wasiliana,
+            recipients: phone_number.map { |number| build_recipient(number, body) },
+            raw: body
+          )
+        )
+      end
+
+      def build_recipient(number, body)
+        SendResult::Recipient.new(
+          number: number,
+          success: true,
+          message_id: airtime_uid,
+          status: body["message"]
+        )
+      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["code"] || body.to_s
+      end
+    end
+  end
+end
+
+Arafa.register(:airtime_wasiliana, Arafa::Airtime::Wasiliana)

data/lib/arafa/configuration.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "dry/configurable"
+require "logger"
+
+module Arafa
+  # Dry::Configurable settings, nested per provider.
+  #
+  #   Arafa.configure do |config|
+  #     config.wasiliana.api_key = ENV["WASILIANA_API_KEY"]
+  #     config.africas_talking.api_key = ENV["AT_API_KEY"]
+  #     config.africas_talking.username = ENV["AT_USERNAME"]
+  #   end
+  module Configuration
+    extend Dry::Configurable
+
+    setting :open_timeout, default: 5
+    setting :timeout, default: 10
+    setting :default_sender, default: nil
+    setting :logger, default: Logger.new($stdout)
+
+    setting :africas_talking do
+      setting :api_key, default: nil
+      setting :username, default: nil
+      setting :wa_number, default: nil
+      setting :sandbox, default: false
+    end
+
+    setting :wasiliana do
+      setting :api_key, default: nil
+    end
+  end
+end

data/lib/arafa/contracts/africas_talking_airtime_contract.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "airtime_contract"
+
+module Arafa
+  module Contracts
+    # Africa's Talking's airtime API (§1.10) has no callback field at all —
+    # unlike Wasiliana, which needs one for delivery-report webhooks — so
+    # `callback` is downgraded from required to optional here. AT also caps
+    # requests at 1,000 recipients and requires a configured application
+    # username, same business-rule-against-config pattern as
+    # `AfricasTalkingContract` for SMS.
+    class AfricasTalkingAirtimeContract < AirtimeContract
+      option :username, default: -> { Arafa.config.africas_talking.username }
+
+      params do
+        optional(:callback).filled(:string)
+      end
+
+      rule(:phone_number) do
+        key.failure("must not exceed 1,000 recipients") if values[:phone_number].size > 1000
+      end
+
+      rule do
+        base.failure("Africa's Talking username is not configured") if username.to_s.empty?
+      end
+    end
+  end
+end

data/lib/arafa/contracts/africas_talking_contract.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "base_contract"
+
+module Arafa
+  module Contracts
+    # Africa's Talking requires a registered senderId (mapped from `from:`)
+    # on every send, plus a configured application username — the latter
+    # isn't part of the outgoing payload itself, so it's checked as a
+    # business rule against config/state rather than a structural field.
+    class AfricasTalkingContract < BaseContract
+      option :username, default: -> { Arafa.config.africas_talking.username }
+
+      params do
+        required(:from).filled(:string)
+      end
+
+      rule(:from) do
+        key.failure("must be 11 characters or fewer") if values[:from].to_s.length > 11
+      end
+
+      rule do
+        base.failure("Africa's Talking username is not configured") if username.to_s.empty?
+      end
+    end
+  end
+end

data/lib/arafa/contracts/airtime_contract.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+require "uri"
+
+module Arafa
+  module Contracts
+    # Structural + business rules for an outgoing airtime request (§1.6),
+    # applied before any HTTP call is made. Doesn't share `BaseContract`
+    # since airtime payloads have nothing in common with an SMS `to:`/`text:`
+    # payload.
+    class AirtimeContract < Dry::Validation::Contract
+      params do
+        required(:phone_number).array(:string)
+        required(:currency_code).filled(:string)
+        required(:amount).filled
+        required(:callback).filled(:string)
+        optional(:airtime_uid).filled(:string)
+      end
+
+      rule(:phone_number) do
+        key.failure("must include at least one recipient") if values[:phone_number].empty?
+      end
+
+      rule(:currency_code) do
+        key.failure("must be a 3-letter ISO currency code") unless values[:currency_code].to_s.match?(/\A[A-Z]{3}\z/)
+      end
+
+      rule(:amount) do
+        numeric = begin
+          Float(values[:amount])
+        rescue ArgumentError, TypeError
+          nil
+        end
+
+        key.failure("must be a positive number") if numeric.nil? || numeric <= 0
+      end
+
+      rule(:callback) do
+        next unless key?(:callback)
+
+        uri = begin
+          URI.parse(values[:callback].to_s)
+        rescue URI::InvalidURIError
+          nil
+        end
+
+        key.failure("must be a valid http(s) URL") unless uri.is_a?(URI::HTTP) && !uri.host.nil?
+      end
+    end
+  end
+end

data/lib/arafa/contracts/base_contract.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module Arafa
+  module Contracts
+    # Shared `to:`/`text:`/`from:` structural and business rules applied to
+    # every provider's outgoing SMS payload before any HTTP call is made.
+    class BaseContract < Dry::Validation::Contract
+      params do
+        required(:to).array(:string)
+        required(:text).filled(:string)
+        optional(:from).filled(:string)
+      end
+
+      rule(:to) do
+        key.failure("must include at least one recipient") if values[:to].empty?
+      end
+    end
+  end
+end

data/lib/arafa/contracts/mobile_data_contract.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "dry/validation"
+
+module Arafa
+  module Contracts
+    # Africa's Talking Mobile Data API (§1.12). Unlike airtime, each recipient
+    # carries its own bundle shape (`quantity`/`unit`/`validity`), so the
+    # enum/positivity checks run per-recipient rather than once against a
+    # single shared `amount`. Same "configured application username" business
+    # rule as `AfricasTalkingAirtimeContract`, since AT has no equivalent in
+    # Wasiliana for this product.
+    class MobileDataContract < Dry::Validation::Contract
+      UNITS = %w[MB GB].freeze
+      VALIDITIES = %w[Day Week BiWeek Month Quarterly].freeze
+
+      option :username, default: -> { Arafa.config.africas_talking.username }
+
+      params do
+        required(:product_name).filled(:string)
+        required(:recipients).array(:hash) do
+          required(:phone_number).filled(:string)
+          required(:quantity).filled
+          required(:unit).filled(:string)
+          required(:validity).filled(:string)
+          optional(:metadata).hash
+        end
+      end
+
+      rule(:recipients) do
+        key.failure("must include at least one recipient") if values[:recipients].empty?
+      end
+
+      rule(:recipients).each do
+        next unless key?
+
+        unless value[:phone_number].to_s.match?(/\A254(7|1)\d{8}\z/)
+          key.failure("phone_number must be a valid Kenyan MSISDN")
+        end
+
+        key.failure("unit must be one of MB, GB") unless UNITS.include?(value[:unit])
+
+        unless VALIDITIES.include?(value[:validity])
+          key.failure("validity must be one of Day, Week, BiWeek, Month, Quarterly")
+        end
+
+        numeric = begin
+          Float(value[:quantity])
+        rescue ArgumentError, TypeError
+          nil
+        end
+        key.failure("quantity must be a positive number") if numeric.nil? || numeric <= 0
+      end
+
+      rule do
+        base.failure("Africa's Talking username is not configured") if username.to_s.empty?
+      end
+    end
+  end
+end

data/lib/arafa/contracts/wasiliana_contract.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "base_contract"
+
+module Arafa
+  module Contracts
+    # Wasiliana requires `from` (a Sender ID or ShortCode) on every send,
+    # caps `text` at 918 characters (6 concatenated SMS parts), and accepts
+    # an optional `is_otp` flag that must be a boolean or a "true"/"false"
+    # string per §1.4.
+    class WasilianaContract < BaseContract
+      params do
+        required(:from).filled(:string)
+        optional(:is_otp)
+      end
+
+      rule(:text) do
+        key.failure("must be 918 characters or fewer") if values[:text].to_s.length > 918
+      end
+
+      rule(:is_otp) do
+        next unless key?(:is_otp)
+        next if values[:is_otp].nil?
+
+        allowed = [true, false, "true", "false"]
+        key.failure("must be a boolean or 'true'/'false' string") unless allowed.include?(values[:is_otp])
+      end
+    end
+  end
+end