afconwave 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c800c0e3b437a939afb9da71063c62b0ddc93416ad54bf21d7004519c1aa33ee
+  data.tar.gz: 9e347465ac42a572ee570df78a3b5a574a41e6033dde417dde769f16ea890893
+SHA512:
+  metadata.gz: 10fd15f5d2dfa7e9e92b66ff19a6562af5cebf4e31f353635e0509fee588f831234ad2d3dc2bec33bde58a10dd7966fe357782ab3fb51ff37c987e0262169851
+  data.tar.gz: 78c6052b92c89addbf87c4291c8b6ea9a2cbe0ee5495277a813280aa9f923cb8d78b25f967a124bb107b30b1196bb373ee45f46e17acd4fc934c4cbe10dae3b8

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AfconWave
+
+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,144 @@
+# afconwave — Official Ruby SDK
+
+> The official Ruby client library for the AfconWave Payments API.
+
+[![Gem Version](https://badge.fury.io/rb/afconwave.svg)](https://badge.fury.io/rb/afconwave)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## Features
+
+- ✅ Simple, clean Ruby API
+- 🌍 Payments, Payouts, and Refunds
+- 🔒 Secure HMAC-SHA256 signature verification
+- 🧪 Sandbox-ready with test keys
+- 📦 Lightweight, zero external dependencies (uses `net/http`)
+
+---
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'afconwave'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install afconwave
+```
+
+---
+
+## Quick Start
+
+```ruby
+require 'afconwave'
+
+afw = AfconWave::Client.new(secret_key: 'sk_test_your_key_here')
+```
+
+---
+
+## Usage Guide
+
+### Create a Payment
+
+```ruby
+payment = afw.create_payment(
+  amount: 5000,            # Amount in minor units (5000 = 50 XAF)
+  currency: 'XAF',
+  description: 'Order #1234',
+  callback_url: 'https://yoursite.com/payment/callback',
+  customer: {
+    name: 'Jean Dupont',
+    email: 'jean@example.com'
+  }
+)
+
+puts payment['checkout_url'] # Redirect user here
+puts payment['id']           # e.g., pay_507f191e8180f
+```
+
+### Retrieve a Payment
+
+```ruby
+payment = afw.retrieve_payment('pay_507f191e8180f')
+
+puts payment['status']   # "pending" | "success" | "failed"
+puts payment['amount']
+```
+
+### List Payments
+
+```ruby
+result = afw.list_payments(limit: 20, status: 'success')
+
+result['data'].each do |payment|
+  puts "#{payment['id']} - #{payment['amount']} #{payment['currency']}"
+end
+```
+
+### Webhook Verification
+
+```ruby
+# In a Rails controller
+def webhook
+  payload = request.raw_post
+  signature = request.headers['X-AfconWave-Signature']
+  secret = ENV['AFCONWAVE_WEBHOOK_SECRET']
+
+  is_valid = AfconWave::Client.verify_webhook_signature(
+    payload: payload,
+    signature: signature,
+    secret: secret
+  )
+
+  if is_valid
+    event = JSON.parse(payload)
+    # Handle event...
+    render json: { status: 'ok' }, status: 200
+  else
+    render json: { error: 'Invalid signature' }, status: 400
+  end
+end
+```
+
+---
+
+## Error Handling
+
+```ruby
+begin
+  payment = afw.create_payment(...)
+rescue AfconWave::AuthError => e
+  puts "Invalid API Key: #{e.message}"
+rescue AfconWave::Error => e
+  puts "API Error #{e.status_code}: #{e.message}"
+end
+```
+
+---
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `secret_key` | `String` | **required** | Your AfconWave secret API key |
+| `base_url` | `String` | `https://api.afconwave.com/v1` | API base URL |
+| `timeout` | `Integer` | `30` | Request timeout in seconds |
+
+---
+
+## License
+
+MIT © AfconWave

data/lib/afconwave/version.rb

@@ -0,0 +1,3 @@
+module AfconWave
+  VERSION = "1.0.0"
+end

data/lib/afconwave.rb

@@ -0,0 +1,150 @@
+require 'uri'
+require 'net/http'
+require 'json'
+require 'openssl'
+require_relative 'afconwave/version'
+
+module AfconWave
+  # Shortcut to create a new client
+  def self.new(secret_key:, **options)
+    Client.new(secret_key: secret_key, **options)
+  end
+  # ─── Exceptions ──────────────────────────────────────────────────────────────
+
+  class Error < StandardError
+    attr_reader :status_code, :code
+
+    def initialize(message, status_code: nil, code: nil)
+      @status_code = status_code
+      @code = code
+      super(message)
+    end
+  end
+
+  class AuthError < Error; end
+  class PaymentError < Error; end
+
+  # ─── Main Client ──────────────────────────────────────────────────────────────
+
+  class Client
+    attr_accessor :secret_key, :base_url, :timeout
+
+    def initialize(secret_key:, base_url: 'https://api.afconwave.com/api/v1', timeout: 30)
+      @secret_key = secret_key
+      @base_url = base_url
+      @timeout = timeout
+    end
+
+    def self.verify_webhook_signature(payload:, signature:, secret:, tolerance: 300)
+      # 1. Verify Signature (timing-safe compare via OpenSSL stdlib)
+      expected = OpenSSL::HMAC.hexdigest('sha256', secret, payload)
+
+      # OpenSSL.fixed_length_secure_compare requires equal-length inputs.
+      return false unless signature.is_a?(String) && expected.bytesize == signature.bytesize
+      return false unless OpenSSL.fixed_length_secure_compare(expected, signature)
+
+      # 2. Verify Timestamp (Replay Protection)
+      begin
+        data = JSON.parse(payload)
+        if data['timestamp']
+          current_time = Time.now.to_i # seconds
+          webhook_time = data['timestamp'] / 1000 # convert ms to seconds
+          age = (current_time - webhook_time).abs
+
+          return false if age > tolerance
+        end
+      rescue JSON::ParserError
+        # Non-JSON payload, signature is valid but can't check timestamp
+      end
+
+      true
+    end
+
+    def payments; @payments ||= Resource::Payments.new(self); end
+    def payouts; @payouts ||= Resource::Payouts.new(self); end
+    def crypto; @crypto ||= Resource::Crypto.new(self); end
+    def refunds; @refunds ||= Resource::Refunds.new(self); end
+    def disputes; @disputes ||= Resource::Disputes.new(self); end
+
+    def request(method:, path:, data: nil, params: nil)
+      uri = URI("#{base_url}#{path}")
+      uri.query = URI.encode_www_form(params) if params
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true if uri.scheme == 'https'
+      http.read_timeout = @timeout
+
+      req = case method.upcase
+            when 'POST'
+              request = Net::HTTP::Post.new(uri)
+              request.body = data.to_json if data
+              request
+            when 'GET'
+              Net::HTTP::Get.new(uri)
+            else
+              raise Error.new("Unsupported method #{method}")
+            end
+
+      req['Authorization'] = "Bearer #{secret_key}"
+      req['Content-Type'] = 'application/json'
+      req['Accept'] = 'application/json'
+
+      response = http.request(req)
+      res_data = JSON.parse(response.body) rescue { 'error' => 'Invalid JSON response' }
+
+      unless response.is_a?(Net::HTTPSuccess)
+        case response.code.to_i
+        when 401 then raise AuthError.new(res_data['error'] || 'Invalid API Key', status_code: 401)
+        else raise Error.new(res_data['error'] || response.message, status_code: response.code.to_i, code: res_data['code'])
+        end
+      end
+
+      res_data['data'] || res_data
+    end
+
+    # ─── Top-level Convenience Methods (Matches README) ─────────────────────
+
+    def create_payment(**data); payments.create(**data); end
+    def retrieve_payment(id); payments.retrieve(id); end
+    def list_payments(**params); payments.list(**params); end
+    def create_payout(**data); payouts.create(**data); end
+  end
+
+  module Resource
+    class Base
+      def initialize(client); @client = client; end
+    end
+
+    class Payments < Base
+      def create(**data); @client.request(method: 'POST', path: '/payments', data: data); end
+      def retrieve(id); @client.request(method: 'GET', path: "/payments/#{id}"); end
+      def list(**params); @client.request(method: 'GET', path: '/payments', params: params); end
+    end
+
+    class Payouts < Base
+      def create(**data); @client.request(method: 'POST', path: '/payouts', data: data); end
+      def retrieve(id); @client.request(method: 'GET', path: "/payouts/#{id}"); end
+    end
+
+    class Crypto < Base
+      def buy(**data); @client.request(method: 'POST', path: '/crypto/buy', data: data); end
+    end
+
+    class Refunds < Base
+      def create(payment_id:, amount:, reason: nil)
+        @client.request(method: 'POST', path: '/refunds', data: { paymentId: payment_id, amount: amount, reason: reason })
+      end
+      def list; @client.request(method: 'GET', path: '/refunds'); end
+    end
+
+    class Disputes < Base
+      def open(transaction_id:, reason:, description:)
+        @client.request(method: 'POST', path: '/disputes', data: { transactionId: transaction_id, reason: reason, description: description })
+      end
+      def list; @client.request(method: 'GET', path: '/disputes'); end
+      def resolve(dispute_id:, resolution:, resolution_details: nil)
+        @client.request(method: 'POST', path: "/disputes/#{dispute_id}/resolve", data: { resolution: resolution, resolutionDetails: resolution_details })
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: afconwave
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- AfconWave Team
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-10 00:00:00.000000000 Z
+dependencies: []
+description: Integrate AfconWave payments, payouts, and refunds into your Ruby or
+  Rails applications.
+email:
+- support@afconwave.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/afconwave.rb
+- lib/afconwave/version.rb
+homepage: https://github.com/afconwave/afconwave-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the AfconWave Payments API
+test_files: []