arafa 0.1.0

data/implementation_plan.md

@@ -0,0 +1,610 @@
+# Arafa Implementation Plan
+
+`arafa` is a Ruby gem giving a single, uniform interface to multiple SMS/USSD/Airtime
+gateways used in Kenya. This document is the reference for implementing the gem,
+starting with two providers: **Africa's Talking** and **Wasiliana**. Additional
+providers plug into the same interface later without changing calling code.
+
+Africa's Talking exposes more than SMS/USSD — §1.10–§1.13 cover its Airtime, Voice,
+Mobile Data, and WhatsApp APIs, since Wasiliana only offers SMS/USSD/Airtime and this gem
+otherwise undersells what AT alone can do.
+
+Target usage:
+
+```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
+
+provider = Arafa::Wasiliana.new(text: "Hello", to: "0728833100")
+result = provider.send
+result.success? # => true
+result.value!.message_id
+```
+
+## 1. Provider API reference
+
+These fields were captured directly from each provider's live documentation
+(`developers.africastalking.com`, `docs.wasiliana.ke`) — not guessed.
+
+### 1.1 Africa's Talking — Bulk SMS
+
+| | |
+|---|---|
+| Endpoint (live) | `POST https://api.africastalking.com/version1/messaging/bulk` |
+| Endpoint (sandbox) | `POST https://api.sandbox.africastalking.com/version1/messaging/bulk` — marked "coming soon" in AT's own docs, treat as unavailable for now |
+| Headers | `apiKey: <API_KEY>`, `Content-Type: application/json`, `Accept: application/json` |
+
+Request body (JSON):
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `username` | String | yes | AT application username |
+| `phoneNumbers` | Array\<String\> | yes | E.164 numbers |
+| `message` | String | yes | |
+| `senderId` | String | yes | Registered short code or alphanumeric |
+| `enqueue` | Integer | no | 1 = async queue (default), 0 = sync |
+
+Response:
+
+```json
+{
+  "SMSMessageData": {
+    "Message": "Sent to 1/1 Total Cost: KES 0.8000",
+    "Recipients": [
+      {"statusCode": 101, "number": "+254711XXXYYY", "status": "Success", "cost": "KES 0.8000", "messageId": "ATPid_SampleTxnId123"}
+    ]
+  }
+}
+```
+
+`statusCode` values: `100` Processed, `101` Sent, `102` Queued (all treated as success);
+`401` RiskHold, `402` InvalidSenderId, `403` InvalidPhoneNumber, `404` UnsupportedNumberType,
+`405` InsufficientBalance, `406` UserInBlacklist, `407` CouldNotRoute, `409` DoNotDisturbRejection,
+`500` InternalServerError, `501` GatewayError, `502` RejectedByGateway (all treated as
+per-recipient failures — the HTTP call itself can still return 200 with some recipients
+failed, so failures must be read out of `Recipients`, not just the HTTP status).
+
+### 1.2 Africa's Talking — USSD (inbound only)
+
+AT does not expose an outbound "send USSD" call. Instead:
+
+1. You register a service code and a callback URL with AT.
+2. AT `POST`s to your callback URL as `application/x-www-form-urlencoded` with:
+   `sessionId`, `phoneNumber`, `serviceCode`, `text`, `networkCode`.
+3. You must respond within 10 seconds with `Content-Type: text/plain`, body prefixed
+   `CON ` (session continues, more input expected) or `END ` (session terminates).
+
+### 1.3 Wasiliana — Authentication
+
+| | |
+|---|---|
+| Header | `apiKey: <API_KEY>` (obtained from the Wasiliana account dashboard) |
+| Content type | `application/json` for all requests |
+
+### 1.4 Wasiliana — SMS send
+
+Same endpoint is documented under both "Sender ID" and "ShortCode" pages — it is one
+unified send endpoint; `from` carries either a registered Sender ID or a ShortCode.
+
+| | |
+|---|---|
+| Endpoint | `POST https://api.wasiliana.com/api/v1/send/sms` |
+| Headers | `Content-Type: application/json`, `apiKey: <API_KEY>` |
+
+Request body:
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `recipients` | Array\<String\> | yes | Phone numbers |
+| `from` | String | yes | Sender ID or ShortCode |
+| `message` | String | yes | |
+| `linkid` | String | no | Returned on inbound-triggered replies |
+| `message_uid` | String | no | Your own idempotency/tracking id, echoed to delivery-report callback |
+| `is_otp` | String/Bool | no | Marks message as an OTP type |
+
+Response (success):
+
+```json
+{"status": "success", "data": "Successfully Dispatched the sms to process"}
+```
+
+Failure shape is not documented beyond the HTTP status code table (see 1.7) — implement
+defensively: any non-2xx, or a 2xx body where `status != "success"`, is a failure.
+
+### 1.5 Wasiliana — USSD (inbound only)
+
+Same inbound-webhook model as AT. Wasiliana `POST`s JSON to your registered callback:
+
+```json
+{"sessionId": "453720679", "phoneNumber": "25479XXX2541", "serviceCode": "665", "text": "3", "ussdId": "158"}
+```
+
+**Not documented**: the expected response contract (whether it follows the same
+`CON`/`END` text convention as AT, a different prefix, or a JSON response). Treat as
+`CON`/`END` by default (industry-standard convention shared by AT-compatible gateways)
+but flag this explicitly to be verified against a live Wasiliana sandbox/service before
+relying on it in production.
+
+### 1.6 Wasiliana — Airtime
+
+| | |
+|---|---|
+| Endpoint | `POST https://api.wasiliana.com/api/v1/airtime/request` |
+| Headers | `Content-Type: application/json`, `apiKey: <API_KEY>` |
+
+| Field | Type | Required |
+|---|---|---|
+| `phone_number` | String (docs show it array-wrapped — verify empirically) | yes |
+| `currency_code` | String, e.g. `"KES"` | yes |
+| `amount` | String/Number | yes |
+| `callback` | String (URL) | yes |
+| `airtime_uid` | String | no |
+
+Response: `{"status": "success", "message": "Request has been sent successfully"}`.
+
+### 1.7 Wasiliana — Delivery reports (inbound callback)
+
+```json
+{"phone": ["25472x xxx xxx"], "correlator": "message_15883801465eacc1f2643a9", "deliveryStatus": "0"}
+```
+
+### 1.8 Wasiliana — HTTP error codes
+
+| Code | Meaning |
+|---|---|
+| 400 | Bad Request — invalid request |
+| 401 | Unauthorized — wrong API key |
+| 403 | Forbidden — escalated access |
+| 404 | Not Found |
+| 405 | Method Not Allowed |
+| 406 | Not Acceptable — non-JSON format requested |
+| 429 | Too Many Requests |
+| 500 | Internal Server Error |
+| 503 | Service Unavailable |
+
+Error body shape: `{"message": "...", "error": "...", "code": "401"}`.
+
+### 1.9 Phone number normalization
+
+Neither provider documents accepting local Kenyan formats (`07...`, `01...`). The gem
+must normalize `to:`/`recipients` before sending: `07XXXXXXXX` / `01XXXXXXXX` → `2547XXXXXXXX`
+/ `2541XXXXXXXX`; `+254...` → `254...` (strip leading `+`); reject anything that doesn't
+match a valid Kenyan MSISDN after normalization.
+
+### 1.10 Africa's Talking — Airtime
+
+Contrary to §8's original open item, AT does document an outbound Airtime API — implement
+it alongside Wasiliana's.
+
+| | |
+|---|---|
+| Endpoint (live) | `POST https://api.africastalking.com/version1/airtime/send` |
+| Endpoint (sandbox) | `POST https://api.sandbox.africastalking.com/version1/airtime/send` |
+| Headers | `apiKey`, `Content-Type: application/json`, `Accept: application/json`, optional `Idempotency-Key` |
+
+Request body:
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `username` | String | yes | |
+| `recipients` | Array\<Hash\> | yes | `[{"phoneNumber": "+254711XXXYYY", "amount": "KES 100.50"}]` — amount is `<3-letter currency> <decimal>` as one string |
+| `maxNumRetry` | Integer | no | Retry window in hours, default 8, retried every 60s |
+| `requestMetadata` | Hash\<String,String\> | no | Free-form string metadata echoed back |
+
+Response: `numSent`, `totalAmount`, `totalDiscount`, `responses` (per-recipient `phoneNumber`,
+`amount`, `discount`, `status` [`Sent`/`Failed`], `requestId` or `None`, `errorMessage` or
+`None`), top-level `errorMessage` if the whole request was rejected. Max 1,000 recipients per
+request. Duplicate requests within 5 minutes are rejected unless an `Idempotency-Key` header
+is supplied (shared mechanism, also used by Mobile Data — see §1.12).
+
+### 1.11 Africa's Talking — Voice
+
+Outbound calling, unlike USSD this *does* have a send call, plus an inbound callback model
+for handling the call once connected.
+
+| | |
+|---|---|
+| Endpoint (live) | `POST https://voice.africastalking.com/call` |
+| Headers | `apiKey`, `Content-Type: application/x-www-form-urlencoded` (or `multipart/form-data`), `Accept: application/json` |
+
+Request body (form-encoded, not JSON — differs from every other AT product):
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `username` | String | yes | |
+| `from` | String | yes | AT phone number, `+XXXYYYYYY` |
+| `to` | String | yes | Comma-separated recipient numbers |
+| `clientRequestId` | String | no | Echoed to the events callback URL |
+
+Response is XML (not JSON, another outlier): `entries` (list of `{phoneNumber, status,
+sessionId}`, `status` one of `Queued`/`InvalidPhoneNumber`/`DestinationNotSupported`/
+`InsufficientCredit`) and optional top-level `errorMessage`. Response header
+`X-Current-Queue-Size` reports queue depth.
+
+Inbound: AT calls the registered callback URL as the call progresses (call connected, digits
+gathered, call ended); the callback response body is XML built from a small DSL of verbs
+(`Say`, `Play`, `GetDigits`, `Dial`, `Record`, `Enqueue`/`Call Queue`, `Redirect`, `Reject`,
+`Conference`) — same shape as the USSD callback model in §1.2 but XML-bodied rather than
+`CON`/`END` text. Treat as a second callback-only surface, out of scope for the first pass
+(flagged in §8) given its size; land Voice *sending* (`#send`-shaped, matches existing
+providers) before the call-control DSL.
+
+### 1.12 Africa's Talking — Mobile Data
+
+| | |
+|---|---|
+| Endpoint (live) | `POST https://bundles.africastalking.com/mobile/data/request` |
+| Endpoint (sandbox) | `POST https://bundles.sandbox.africastalking.com/mobile/data/request` |
+| Headers | `apiKey`, `Content-Type: application/json`, `Accept: application/json`, optional `Idempotency-Key` |
+
+Request body:
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `username` | String | yes | |
+| `productName` | String | yes | AT application product name |
+| `recipients` | Array\<Hash\> | yes | `{phoneNumber, quantity, unit ("MB"/"GB"), validity ("Day"/"Week"/"BiWeek"/"Month"/"Quarterly"), metadata: Hash<String,String>}` |
+
+Response: `entries` (per-recipient `phoneNumber`, `provider`, `status` [`Queued`], `transactionId`,
+`value`). Same idempotency window/header as Airtime (§1.10).
+
+### 1.13 Africa's Talking — WhatsApp
+
+| | |
+|---|---|
+| Endpoint (live) | `POST https://chat.africastalking.com/whatsapp/message/send` |
+| Endpoint (sandbox) | marked "coming soon" — production only for now, same caveat as §1.1's sandbox note |
+| Headers | `apikey` (lowercase, unlike every other AT product's `apiKey`), `Content-Type: application/json` |
+
+Request body: `username`, `waNumber` (the registered AT WhatsApp number), `phoneNumber`
+(recipient), `body` — a polymorphic object depending on message type:
+
+| Message type | `body` shape |
+|---|---|
+| Text | `{message}` |
+| Media | `{mediaType: Image\|Video\|Audio\|Sticker\|Document\|Voice, url, caption}` |
+| Template | `{templateId, headerValue, bodyValues: Array<String>}` |
+| Interactive buttons | `{action: {buttons: [{id, title}]}, body: {text}, header: {text}}` |
+| Interactive list | `{action: {button, sections: [{title, rows: [{id, title, description}], product_items}]}, body: {text}, header: {text}, footer: {text}}` |
+
+Response: `status` (`SENT`/`DELIVERED`/`FAILED`/`READ`/`DELETED`), `phoneNumber`, `messageId`
+(only present on success). Given the five message shapes, `body` is modeled as a
+`Dry::Struct` per message kind (`MessageBody::Text`/`Media`/`Template`, plus
+`MessageBody::Interactive::Buttons`/`List` for the two nested interactive shapes) rather
+than one contract covering all fields as optional (mirrors how `dry-types` sum types are
+already used for the Wasiliana airtime `phone_number` ambiguity in §5.2).
+
+## 2. Gem dependencies
+
+Runtime (`arafa.gemspec`):
+
+| Gem | Purpose |
+|---|---|
+| `faraday` (~> 2.0) | HTTP client |
+| `faraday-retry` | Retry transient 5xx/429 responses |
+| `dry-configurable` (~> 1.0) | `Arafa.configure` block, per-provider settings |
+| `dry-initializer` (~> 3.0) | Keyword-arg constructors (`Wasiliana.new(text:, to:, from: nil)`) |
+| `dry-types` (~> 1.8) | Leaf value types with coercion/constraints (`PhoneNumber`, `SenderId`, `MessageText`) |
+| `dry-struct` (~> 1.0) | Typed value objects built from `dry-types` (`Message`, `SendResult`) |
+| `dry-schema` (~> 1.14) | Structural coercion/validation of *raw* input hashes: inbound USSD/delivery-report webhook params, airtime request params |
+| `dry-validation` (~> 1.11) | Per-provider `Contract`s applying business rules to the *outgoing* send/airtime payload before any HTTP call is made |
+| `dry-monads` (~> 1.0) | `Success`/`Failure` results from `#send` instead of raising on expected provider errors |
+| `ox` or stdlib `rexml` | Parse Voice's XML response body (§1.11) — only AT product that isn't JSON; stdlib `rexml` avoids a new dependency and Voice's response shape is small enough not to need a faster parser |
+
+Dev (`Gemfile`, existing minitest/rubocop setup): add `webmock` for HTTP stubbing in tests,
+and `vcr` for recorded-cassette integration tests (see §8).
+
+## 3. File layout
+
+```
+lib/arafa.rb                            # requires everything, top-level module
+lib/arafa/version.rb                    # existing
+lib/arafa/configuration.rb              # Dry::Configurable settings, nested per provider
+lib/arafa/types.rb                      # Dry::Types module (PhoneNumber, SenderId, MessageText, ...)
+lib/arafa/errors.rb                     # Error hierarchy
+lib/arafa/phone_number.rb               # Kenyan MSISDN normalizer (used by the PhoneNumber type's constructor)
+lib/arafa/message.rb                    # Dry::Struct: to (Array<PhoneNumber>), text, from
+lib/arafa/send_result.rb                # Dry::Struct: normalized success/failure result
+lib/arafa/schemas/ussd_callback_schema.rb    # Dry::Schema::Params — shared shape for inbound USSD webhook params
+lib/arafa/schemas/delivery_report_schema.rb  # Dry::Schema::JSON — Wasiliana delivery-report callback body
+lib/arafa/schemas/airtime_request_schema.rb  # Dry::Schema::JSON — Wasiliana airtime request params
+lib/arafa/contracts/base_contract.rb         # Dry::Validation::Contract — shared to:/text: rules
+lib/arafa/contracts/africas_talking_contract.rb  # + senderId/username rules
+lib/arafa/contracts/wasiliana_contract.rb        # + from/is_otp rules
+lib/arafa/contracts/airtime_contract.rb          # amount/currency_code/callback URL rules
+lib/arafa/providers/base.rb             # dry-initializer ctor, Faraday builder, contract validation, #send template method
+lib/arafa/providers/africas_talking.rb  # Arafa::AfricasTalking < Base
+lib/arafa/providers/wasiliana.rb        # Arafa::Wasiliana < Base
+lib/arafa/ussd/request.rb               # Dry::Struct: normalized inbound USSD request
+lib/arafa/ussd/response.rb              # .continue(text) / .end(text) -> "CON "/"END " string
+lib/arafa/ussd/africas_talking.rb       # parses AT's form-encoded callback params via UssdCallbackSchema
+lib/arafa/ussd/wasiliana.rb             # parses Wasiliana's JSON callback params via UssdCallbackSchema
+lib/arafa/airtime/wasiliana.rb          # Arafa::Airtime::Wasiliana — airtime request wrapper
+lib/arafa/airtime/africas_talking.rb    # Arafa::Airtime::AfricasTalking per §1.10
+lib/arafa/contracts/mobile_data_contract.rb      # quantity/unit/validity rules, §1.12
+lib/arafa/data/africas_talking.rb       # Arafa::Data::AfricasTalking — mobile data send, §1.12
+lib/arafa/voice/africas_talking.rb      # Arafa::Voice::AfricasTalking — outbound call, §1.11 (send only, no call-control DSL yet)
+lib/arafa/whatsapp/africas_talking.rb   # Arafa::Whatsapp::AfricasTalking — text/media/template/interactive send, §1.13
+lib/arafa/whatsapp/message_body.rb      # Dry::Struct sum type covering all five body shapes, §1.13
+```
+
+`Arafa::AfricasTalking` and `Arafa::Wasiliana` are the public entry points matching the
+requested call shape; everything else (USSD parsing, airtime) lives under sub-namespaces
+since they aren't the `#send` SMS flow.
+
+## 4. Architecture
+
+- **Configuration** — `Arafa.configure { |c| c.wasiliana.api_key = ...; c.africas_talking.api_key = ...; c.africas_talking.username = ... }` via `dry-configurable`, so provider instances don't need credentials passed on every call.
+- **`Providers::Base`** — `dry-initializer` constructor accepting `text:`, `to:` (String or Array, run through `PhoneNumber` normalization), optional `from:` (falls back to configured default sender). Defines the template method:
+
+  ```ruby
+  def send
+    response = connection.post(endpoint, build_payload, headers)
+    parse_response(response)
+  rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+    Dry::Monads::Failure(Arafa::NetworkError.new(e.message))
+  end
+
+  def self.send(**kwargs) = new(**kwargs).send
+  ```
+
+  Subclasses implement `#endpoint`, `#headers`, `#build_payload`, `#parse_response`.
+  `#send` returns a `Dry::Monads::Result` — `Success(SendResult)` or `Failure(Arafa::Error subclass)`.
+  The class-level `.send(text:, to:)` shortcut (borrowed from `sms_kit`'s `.deliver`) avoids
+  the `new(...).send` two-step for the common one-off case.
+
+- **Duck-typed messages** — `Base#initialize` accepts either the `text:`/`to:`/`from:`
+  keywords directly, or a single positional object responding to `#to_arafa` returning a
+  hash of the same keywords (mirrors `sms_kit`'s `#to_sms` convention) — lets a calling
+  app pass a domain object (e.g. `OtpMessage#to_arafa`) straight into any provider.
+
+- **Provider registry for dynamic dispatch** — `Arafa.register(:wasiliana, Arafa::Wasiliana)`
+  (providers self-register on load) backing `Arafa.send(:wasiliana, text:, to:)`, so the
+  provider can be chosen at runtime from config/env rather than hardcoding the class name —
+  same idea as `sms_kit`'s `SmsKit::Delivery#deliver(provider, options)`.
+
+- **Shared Faraday connection** — built once in `Base` with JSON request/response
+  middleware and `faraday-retry` (retries 429/5xx with backoff); timeouts pulled from
+  `Arafa.configure`; a `User-Agent: arafa/<VERSION>` header is set on every request
+  (borrowed from `sms_kit`'s `HTTP::USER_AGENT`, useful for providers' own request logs).
+
+- **Logging** — `Arafa.logger` (configurable, defaults to `Logger.new($stdout)`, same
+  pattern as `sms_kit`'s `Logging` module) wired into the Faraday connection as a
+  `f.response :logger, Arafa.logger` middleware so every request/response is logged at
+  `debug`, without each adapter needing to log manually. API keys must be redacted from
+  logged headers.
+
+- **Error hierarchy** — `Arafa::Error` (base) →
+  `Arafa::ValidationError` (payload failed a `dry-schema`/`dry-validation` check, no HTTP
+  call made) · `Arafa::AuthenticationError` (401) · `Arafa::InvalidRequestError` (400/403/406) ·
+  `Arafa::RateLimitError` (429) · `Arafa::ProviderServerError` (500/503) ·
+  `Arafa::NetworkError` (connection-level). Each adapter's `#parse_response` maps the
+  documented status codes/response bodies (§1.1, §1.8) onto these.
+
+- **USSD** — no outbound HTTP call. `Ussd::Request.from_africas_talking(params)` /
+  `Ussd::Request.from_wasiliana(params)` run the raw webhook params through
+  `Schemas::UssdCallbackSchema` (§5) then normalize into one shape (`session_id`,
+  `phone_number`, `service_code`, `text`); `Ussd::Response.continue(text)` /
+  `Ussd::Response.end(text)` build the `CON `/`END `-prefixed plain-text reply. This is
+  documented clearly as a parse/build helper, not a network client, so it isn't confused
+  with `#send`.
+
+- **Airtime** — implemented for both Wasiliana (§1.6) and Africa's Talking (§1.10); both
+  ride the same `Airtime::Base` shape (`recipients`, per-recipient `amount` string,
+  `Dry::Monads::Result` return) even though the wire formats differ, same pattern as
+  `Providers::Base` unifying SMS.
+
+- **Mobile Data** (`Data::AfricasTalking`, §1.12) and **WhatsApp**
+  (`Whatsapp::AfricasTalking`, §1.13) are AT-only for now — Wasiliana doesn't offer either
+  product. They don't extend `Providers::Base` (different payload/response shapes entirely)
+  but follow the same conventions: `dry-initializer` constructor, contract-then-HTTP-call
+  `#send`, `Dry::Monads::Result` return, shared Faraday connection/logger/error hierarchy.
+
+- **Voice** (`Voice::AfricasTalking`, §1.11) ships *send* only in this pass — `POST
+  /call` is a `#send`-shaped call that fits the same `Result`-returning pattern, but it is
+  form-urlencoded and XML-responding rather than JSON like every other AT product, so its
+  adapter needs its own request/response encoding (no reuse of the JSON Faraday builder
+  used elsewhere) and its own XML parser for the `entries`/`errorMessage` response. The
+  inbound call-control callback (the `Say`/`Play`/`GetDigits`/`Dial`/`Record`/`Enqueue`/
+  `Redirect`/`Reject`/`Conference` XML-response DSL) is out of scope for this pass — it's
+  effectively a second product (a full IVR builder) and deserves its own implementation
+  plan once outbound calling and the rest of this plan have shipped.
+
+## 5. Validation with `dry-types`, `dry-schema`, `dry-validation`
+
+These three libraries cover three different jobs and are used in that order, each one
+building on the previous — they are not interchangeable:
+
+| Library | Job | Used for |
+|---|---|---|
+| `dry-types` | Define a single **leaf value's** coercion + constraint | `PhoneNumber`, `SenderId`, `MessageText`, `MsisdnList` |
+| `dry-schema` | Validate the **shape** of a raw hash (presence, type-coerce every key) | Inbound webhook params (USSD callbacks, delivery reports) and the Wasiliana airtime request, where input arrives as an untyped `Hash` (HTTP params/JSON body) |
+| `dry-validation` | Layer **business rules** on top of a schema, with access to config/state | The outgoing SMS/airtime payload, right before a provider adapter makes its HTTP call |
+
+### 5.1 `dry-types` — leaf types (`lib/arafa/types.rb`)
+
+```ruby
+module Arafa
+  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) # 6 concatenated SMS parts
+  end
+end
+```
+
+`Message`/`SendResult` (`dry-struct`) attributes are declared against these types, so a
+malformed phone number or empty message raises `Dry::Struct::Error` the moment the value
+object is built — this is the same coercion mechanism already in §3/§4, just spelled out.
+
+### 5.2 `dry-schema` — raw webhook/param shapes (`lib/arafa/schemas/*.rb`)
+
+Both providers POST inbound webhooks as loosely-typed params (form-encoded for AT USSD,
+JSON for Wasiliana USSD/delivery-reports) — `dry-schema` coerces and validates that shape
+before it's touched by domain code:
+
+```ruby
+module Arafa
+  module Schemas
+    UssdCallbackSchema = Dry::Schema.Params do
+      required(:session_id).filled(:string)
+      required(:phone_number).filled(:string)
+      required(:service_code).filled(:string)
+      required(:text).maybe(:string) # empty text on the very first USSD screen
+    end
+  end
+end
+```
+
+Since AT and Wasiliana use different key names (`sessionId`/`ussdId` vs `sessionId`/
+`ussdId` — actually identical here, but `networkCode` only exists for AT), each
+`Ussd::<Provider>.parse(params)` remaps provider-specific keys to the schema's canonical
+keys first, then calls `UssdCallbackSchema.call(remapped_params)` and reads
+`result.errors.to_h` / `result.to_h`. Same pattern for `DeliveryReportSchema` (§1.7) and
+`AirtimeRequestSchema` (§1.6, including the array-vs-string `phone_number` ambiguity —
+the schema accepts either shape via a sum type and normalizes to an array).
+
+### 5.3 `dry-validation` — per-provider send contracts (`lib/arafa/contracts/*.rb`)
+
+A `Contract` wraps a `params` schema (structural checks) with `rule` blocks (business
+checks that need config/state, e.g. "is a sender ID configured at all"). Adapters call
+their contract **before** touching the network, so bad input never burns an HTTP call:
+
+```ruby
+module Arafa
+  module Contracts
+    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
+
+    class AfricasTalkingContract < BaseContract
+      option :username, default: -> { Arafa.config.africas_talking.username }
+
+      rule do
+        key(:from).failure("senderId is required for Africa's Talking") if values[:from].to_s.empty?
+        base.failure("Africa's Talking username is not configured") if username.to_s.empty?
+      end
+    end
+
+    class WasilianaContract < BaseContract
+      rule(:text) do
+        key.failure("must be 918 characters or fewer") if values[:text].to_s.length > 918
+      end
+    end
+  end
+end
+```
+
+`Providers::Base#send` calls `self.class::CONTRACT.new.call(to:, text:, from:)` first; on
+failure it short-circuits with `Dry::Monads::Failure(Arafa::ValidationError.new(result.errors.to_h))`
+— matching the `Dry::Monads::Result` return shape used for network-level failures, so
+callers handle both the same way:
+
+```ruby
+result = Arafa::Wasiliana.new(text: "", to: "0712345678").send
+result.failure? # => true, no HTTP request was ever sent
+```
+
+## 6. Implementation steps
+
+1. Fill in gemspec `summary`/`description`/`homepage`/`source_code_uri` (currently `TODO`
+   placeholders — blocks clean `bundle install`); add the runtime dependencies from §2.
+2. Core types/errors: `types.rb` (§5.1), `errors.rb` (incl. `Arafa::ValidationError`),
+   `phone_number.rb` (+ unit tests covering `07...`, `01...`, `+254...`, `254...`, invalid
+   input), `message.rb`, `send_result.rb`.
+3. `configuration.rb` with nested `africas_talking`/`wasiliana` settings blocks.
+4. Schemas (§5.2): `UssdCallbackSchema`, `DeliveryReportSchema`, `AirtimeRequestSchema`.
+5. Contracts (§5.3): `BaseContract`, `AfricasTalkingContract`, `WasilianaContract`, `AirtimeContract`
+   (+ unit tests: each documented required/optional field, each business rule, valid/invalid cases).
+6. `Providers::Base` per §4, wired to run its contract before building the HTTP request.
+7. `Providers::AfricasTalking` per §1.1.
+8. `Providers::Wasiliana` per §1.4.
+9. `Ussd::Request`/`Ussd::Response` + per-provider parsers per §1.2/§1.5, built on `UssdCallbackSchema`.
+10. `Airtime::Wasiliana` per §1.6, built on `AirtimeRequestSchema`/`AirtimeContract`.
+11. Minitest coverage (stub HTTP with WebMock, fixtures built from the exact bodies in
+    §1): success + every documented failure status code for AT SMS and Wasiliana SMS;
+    `PhoneNumber` edge cases; contract validation failures short-circuiting before any
+    HTTP stub is hit; USSD parse/build round trips; the `.send` class shortcut,
+    `#to_arafa` duck-typing, and `Arafa.send(:provider, ...)` registry dispatch from §7.
+    Add VCR cassettes (§7) for one recorded success/failure pair per provider.
+12. README: `Arafa::Wasiliana.new(text:, to:).send` example, `Arafa.configure` example,
+    a note that USSD is callback-only (no `#send`-style call), and one example of reading
+    a validation failure from `result.failure`.
+13. `Airtime::AfricasTalking` per §1.10, sharing `Airtime::Base`/`AirtimeContract` shape
+    with the existing Wasiliana adapter; extend `AirtimeContract` for AT's
+    `"<currency> <amount>"` string format and 1,000-recipient cap.
+14. `Data::AfricasTalking` per §1.12: `MobileDataContract` (quantity/unit/validity rules),
+    adapter, tests (success + per-recipient `Queued` status, `Idempotency-Key` header
+    passthrough).
+15. `Whatsapp::AfricasTalking` per §1.13, all five message kinds (text, media, template,
+    interactive buttons, interactive list); `Whatsapp::MessageBody` sum type; tests per
+    message kind plus the `status`/`messageId` response parse.
+16. `Voice::AfricasTalking` per §1.11, outbound `#send` only: form-urlencoded request
+    builder (distinct from the shared JSON Faraday connection), XML response parser,
+    `entries`/`errorMessage`/`X-Current-Queue-Size` mapped onto `SendResult`/error
+    hierarchy. Inbound call-control DSL explicitly deferred — do not start it in this pass.
+17. README: add one example each for Airtime, Mobile Data, and WhatsApp sends, and a note
+    that Voice inbound call handling isn't implemented yet.
+
+## 7. Prior art: `sms_kit` review
+
+[`jamii-Technologies/sms_kit`](https://github.com/jamii-Technologies/sms_kit) is an older,
+similarly-scoped Ruby gem (one interface over multiple SMS gateway adapters, config +
+Faraday-based). It doesn't cover Kenyan providers or USSD/airtime, but several of its
+patterns are directly reusable and are folded into §4 above:
+
+| Idea from `sms_kit` | Where it lands in this plan |
+|---|---|
+| `Provider.deliver(options)` class-method shortcut, skipping `new(...).deliver` | `Base.send(**kwargs)` class method (§4) |
+| `#to_sms` duck-typing so a domain object can be sent directly | `#to_arafa` duck-typing on `Base#initialize` (§4) |
+| `SmsKit::Delivery#deliver(provider_symbol, options)` registry lookup | `Arafa.register` / `Arafa.send(:provider, ...)` registry (§4) |
+| `HTTP::USER_AGENT` constant sent on every request | `User-Agent: arafa/<VERSION>` header on the shared Faraday connection (§4) |
+| `SmsKit::Logging` configurable logger + Faraday `:logger` middleware | `Arafa.logger` + `f.response :logger, Arafa.logger` (§4) |
+| VCR cassettes per provider (`test/fixtures/vcr_cassettes/<provider>/{success,failure}.yml`) alongside plain stub tests | Add `vcr` dev dependency (§2); one recorded cassette pair per provider as a belt-and-suspenders check against the WebMock-stubbed unit tests (step 9) |
+| `Railtie` auto-wiring a Rails log file | Not adopted — out of scope until there's a Rails-integration request; note as a future extension only |
+
+Not adopted: `sms_kit`'s open `Config::Store` (a `Hash` with `method_missing`, untyped) —
+`dry-configurable` already covers this with proper typing/defaults, which is why it was
+chosen over hand-rolling config.
+
+## 8. Open items — needs verification against a live account before shipping
+
+- Wasiliana's USSD callback response contract (`CON`/`END` assumed, unconfirmed).
+- Wasiliana airtime `phone_number` — single string vs. array (docs show it array-wrapped
+  inconsistently with the rest of their examples).
+- Wasiliana failure response body shape for SMS send (only the generic HTTP error-code
+  table is documented, not a send-specific error payload).
+- AT sandbox bulk-SMS endpoint is marked "coming soon" — only production is usable today.
+- AT sandbox WhatsApp endpoint is likewise marked "coming soon" (§1.13) — production only.
+- Gemspec `homepage`/`allowed_push_host`/`source_code_uri` need a real repo URL before
+  this can be published to RubyGems. *(Resolved — see `arafa.gemspec`, points at
+  `github.com/kamalogudah/arafa`.)*
+- Voice's inbound call-control response DSL (§1.11) isn't scoped by this plan at all —
+  needs its own design pass covering the `Say`/`Play`/`GetDigits`/`Dial`/`Record`/
+  `Enqueue`/`Redirect`/`Reject`/`Conference` verbs before implementation starts.
+## 9. Adding a third provider later
+
+Implement `Providers::Base` subclass with `#endpoint`, `#headers`, `#build_payload`,
+`#parse_response`; add a `dry-configurable` settings block for its credentials; a
+`Contracts::<Provider>Contract < Contracts::BaseContract` for any provider-specific rules;
+reuse `PhoneNumber`, `Message`, `SendResult`, and the shared error hierarchy unchanged. If
+the provider has inbound USSD, add a `Ussd::Request.from_<provider>(params)` parser reusing
+the existing `UssdCallbackSchema`/`Ussd::Request`/`Ussd::Response` shapes.