arafa 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e9650757184b4dee784ceb18fb349ee3b3ac97124cf298df249fab5292e33479
+  data.tar.gz: 02775ec8c4cea5c8c2b648bb2d21b0d6f4cd9d8a0dc55d4836f9127e4cb13fe7
+SHA512:
+  metadata.gz: 60110fbec45f0d2c6595d4f96b540c6335c8f06817409afac29a04fed3443ee94b89b53f40c97a7f87c28249be3018793686052da3f5078a12071a1de9128346
+  data.tar.gz: 31234c425a0a109d00aac04f4d12a9d7b49ada54d8416a61fa4ec1ff8d76addd0b7af149215a00e5d7dcb47aa5ab6a6cce0e665937da09b7305e3e88070a8af5

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-08-25
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"arafa" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["mcpaul2058@gmail.com"](mailto:"mcpaul2058@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Paul Oguda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,174 @@
+# Arafa
+
+Arafa gives you a single, uniform Ruby interface to multiple SMS/USSD/Airtime gateways
+used in Kenya, starting with **Africa's Talking** and **Wasiliana**. Every send-shaped
+call returns a `Dry::Monads::Result` —
+`Success(Arafa::SendResult)` or `Failure(Arafa::Error subclass)` — instead of raising on
+expected provider errors, so a rejected phone number or a bad API key is something you
+pattern-match on, not `rescue`.
+
+## Installation
+
+Install the gem and add it to the application's Gemfile by executing:
+
+```bash
+bundle add arafa
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install arafa
+```
+
+## Configuration
+
+Configure credentials once, wherever your app boots (e.g. `config/initializers/arafa.rb`
+in Rails); provider instances then pick them up automatically instead of needing
+credentials passed on every call:
+
+```ruby
+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
+```
+
+Testing against Africa's Talking's sandbox app? Set `config.africas_talking.sandbox = true` to
+route SMS sends through `https://api.sandbox.africastalking.com/version1/messaging` instead of
+the production bulk endpoint, and use the sandbox app's own `username` (`sandbox`) and API key.
+Note the sandbox only delivers to phone numbers registered as Simulator Numbers in the sandbox
+app's dashboard — any other number comes back as a `Failure(Arafa::InvalidRequestError)`.
+
+## Sending an SMS
+
+```ruby
+provider = Arafa::Wasiliana.new(text: "Hello", to: "0728833100")
+result = provider.send
+result.success? # => true
+result.value!.message_id
+```
+
+Wasiliana requires a Sender ID/ShortCode on every send — pass it explicitly with `from:`,
+or set `config.default_sender` once in `Arafa.configure` so every call can omit it, as
+above.
+
+`to:` accepts a single number or an array, in any of the accepted Kenyan formats
+(`07...`, `01...`, `+254...`, `254...`) — Arafa normalizes each one to `2547XXXXXXXX` /
+`2541XXXXXXXX` before it's sent. The same shape works for Africa's Talking:
+
+```ruby
+Arafa::AfricasTalking.new(text: "Hello", to: %w[0711123456 0722334455], from: "MyApp").send
+```
+
+Prefer a one-off call without instantiating the provider yourself? Use the class-level
+shortcut:
+
+```ruby
+Arafa::Wasiliana.send(text: "Hello", to: "0728833100")
+```
+
+Or dispatch to a provider chosen at runtime (e.g. from config/env) by name, via the
+provider registry:
+
+```ruby
+Arafa.send(:wasiliana, text: "Hello", to: "0728833100")
+Arafa.send(:africas_talking, text: "Hello", to: "0728833100", from: "MyApp")
+```
+
+### Reading a validation failure
+
+Requests are validated locally before any HTTP call is made — e.g. Wasiliana requires a
+`from:` Sender ID/ShortCode on every send, so leaving it out (with no
+`default_sender` configured) comes back as `Failure(Arafa::ValidationError)` without
+hitting the network:
+
+```ruby
+result = Arafa::Wasiliana.new(text: "Hello", to: "0728833100").send
+
+result.success? # => false
+result.failure  # => #<Arafa::ValidationError: {from: ["must be filled"]}>
+result.failure.message # => "{from: [\"must be filled\"]}"
+```
+
+Note that malformed input the phone number *type* itself rejects (e.g. `to: "not-a-number"`)
+raises `Dry::Types::ConstraintError` at construction time instead, since it fails before a
+`Dry::Monads::Result` even exists to wrap it — only failures caught by a provider's
+`Contract` (§5.3) come back as `result.failure`.
+
+`result.failure` is always an `Arafa::Error` subclass — `ValidationError` for a rejected
+payload, or `AuthenticationError` / `InvalidRequestError` / `RateLimitError` /
+`ProviderServerError` / `NetworkError` once the request actually reaches the provider
+(see `lib/arafa/errors.rb`).
+
+## USSD (callback-only — no `#send`)
+
+Neither provider exposes an outbound "send USSD" call — USSD is inbound-only. You
+register a service code and callback URL with the provider; they `POST` each subscriber
+interaction to your app, and you must respond within 10 seconds with a `CON `/`END
+`-prefixed plain-text body. Arafa only helps with parsing that inbound payload and
+building the reply — there is no `Arafa::Ussd::Wasiliana.new(...).send`-style call, since
+there's nothing to send:
+
+```ruby
+# Inside your controller/route handling the provider's callback POST:
+request = Arafa::Ussd::Request.from_africas_talking(params)
+# or: Arafa::Ussd::Request.from_wasiliana(params)
+
+if request.text.empty?
+  render plain: Arafa::Ussd::Response.continue("Welcome\n1. Check balance\n2. Buy airtime")
+else
+  render plain: Arafa::Ussd::Response.end("Thanks for using our service")
+end
+```
+
+## Airtime
+
+Top up a subscriber's airtime directly, without going through the SMS/USSD flow. Both
+providers share the same request shape (`phone_number:`, `currency_code:`, `amount:`)
+and return the same `Arafa::SendResult`:
+
+```ruby
+Arafa::Airtime::Wasiliana.new(
+  phone_number: "0712345678",
+  currency_code: "KES",
+  amount: "100.50",
+  callback: "https://example.com/callback"
+).send
+
+Arafa::Airtime::AfricasTalking.new(
+  phone_number: %w[0712345678 0722345678],
+  currency_code: "KES",
+  amount: "100.50"
+).send
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake
+test` to run the tests. You can also run `bin/console` for an interactive prompt that
+will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release
+a new version, update the version number in `version.rb`, and then run `bundle exec rake
+release`, which will create a git tag for the version, push git commits and the created
+tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/kamalogudah/arafa. This project is intended to be a safe, welcoming
+space for collaboration, and contributors are expected to adhere to the [code of
+conduct](https://github.com/kamalogudah/arafa/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT
+License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Arafa project's codebases, issue trackers, chat rooms and
+mailing lists is expected to follow the [code of
+conduct](https://github.com/kamalogudah/arafa/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]