wajub 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d9c7d3e31696d7f37926d39cba029ab759220d634b654cf3612ca3ae1218932a
+  data.tar.gz: ed5abaf317be01db7425470f5a9029b20ed3cf82b026f61f29346296f40ee595
+SHA512:
+  metadata.gz: e060e51ecc44fcf979e9b25f3290ae50101270a046455bf05d63a451abf155f8550fd1ec41f37ea9151372dc548891c67c73bf090041f444493d9066cb4737d2
+  data.tar.gz: 89ee4872f3fac3a97ebbc7484f394487bc434f79aeca1fb320348c9424e6d4a097373cdde0a62afb839290d22f14146bd1e1a30faa5a69cf6780591b5e075a64

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wajub
+
+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,228 @@
+# Wajub Ruby SDK
+
+[![Gem Version](https://img.shields.io/gem/v/wajub)](https://rubygems.org/gems/wajub)
+[![Ruby](https://img.shields.io/badge/Ruby-3.1%2B-red)](https://www.ruby-lang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Official **server-side** SDK for the [Wajub merchant API](https://docs.wajub.com). Accept mobile-money and card payments across Africa with a Stripe-inspired, resource-oriented client.
+
+Use **[Wajub.js](https://docs.wajub.com/libraries/components/js)** for embedded checkout in the browser. Use this SDK on your backend with a secret (`sk_`) or restricted (`rk_`) API key — never expose secret keys in client-side code.
+
+This SDK covers the **merchant API**. It does not wrap checkout session endpoints (`/pay/*`), public link checkout (`/q/*`, `/i/*`), or sandbox simulation — those belong to Wajub.js or direct HTTP during the payment flow.
+
+## Features
+
+- Resource-oriented API (`client.payments`, `client.customers`, …)
+- Automatic `Idempotency-Key` on mutating requests (override per call)
+- Typed errors per HTTP status (`AuthenticationError`, `RateLimitError`, …)
+- Automatic retries on 429 and 5xx (max 2, exponential backoff)
+- Page-based pagination with `auto_paging_each` and `next_page`
+- Webhook signature verification (HMAC-SHA256, timestamp tolerance)
+- Zero third-party runtime dependencies (stdlib only)
+
+## Requirements
+
+| Requirement | Version |
+|-------------|---------|
+| Ruby | 3.1 or later |
+| Dependencies | Standard library only (`net/http`, `openssl`, `json`) |
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'wajub', '~> 1.1'
+```
+
+Or install directly:
+
+```bash
+gem install wajub
+```
+
+## Quick start
+
+Amounts are passed in the **smallest currency unit** (e.g. cents for EUR/USD; whole francs for XAF).
+
+### Redirect checkout
+
+```ruby
+require 'wajub'
+
+client = Wajub::Client.new(api_key: ENV['WAJUB_API_KEY'])
+
+payment = client.payments.create(
+  'amount' => 15_000,
+  'currency' => 'XAF',
+  'email' => 'buyer@example.com',
+  'callback' => 'https://shop.example.com/order/complete'
+)
+
+puts payment.authorization_url
+```
+
+### Inline / overlay (embed token)
+
+```ruby
+embed = client.payments.create(
+  'amount' => 15_000,
+  'currency' => 'XAF',
+  'metadata' => { 'mode' => 'embed' }
+)
+
+# Pass to Wajub.js: embed.authorization_token
+```
+
+`create()` and `retrieve()` return a typed `Payment` object — prefer method access (`payment.authorization_url`). List pages from `list()` yield plain hashes; bracket syntax (`payment['…']`) remains available on typed objects.
+
+## Rails
+
+```ruby
+# config/initializers/wajub.rb
+WajubClient = Wajub::Client.new(
+  api_key: Rails.application.credentials.dig(:wajub, :api_key) || ENV['WAJUB_API_KEY'],
+  webhook_secret: ENV['WAJUB_WEBHOOK_SECRET']
+)
+```
+
+### Webhook controller
+
+Use the **raw request body**:
+
+```ruby
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def wajub
+    event = WajubClient.webhooks.construct_event(
+      request.body.read,  # raw body — not params
+      request.headers['X-Wajub-Signature'],
+      request.headers['X-Wajub-Timestamp']
+    )
+
+    case event['type']
+    when 'payment.succeeded'
+      # fulfill order
+    end
+
+    head :ok
+  rescue Wajub::WebhookSignatureVerificationError
+    head :bad_request
+  end
+end
+```
+
+## Configuration
+
+| Variable | Description |
+|----------|-------------|
+| `WAJUB_API_KEY` | Secret or restricted API key (`sk_`, `sk_test.`, `rk_`, …) |
+| `WAJUB_WEBHOOK_SECRET` | Webhook signing secret (`whsec_`) for `construct_event()` |
+
+Test mode is selected by your API key prefix (`sk_test.…`), not by the API URL. Production calls always go to `https://api.wajub.com`.
+
+## Resources (merchant API)
+
+| Property | Methods |
+|----------|---------|
+| `client.global` | `ping`, `channels`, `countries`, `currencies` |
+| `client.payments` | `create`, `initialize_payment`, `retrieve`, `list`, `cancel`, `process`, `process_split`, `list_refunds` |
+| `client.customers` | `create`, `retrieve`, `update`, `delete`, `list`, `block`, `unblock`, `activate`, `deactivate`, `list_tax_ids`, `create_tax_id`, `delete_tax_id` |
+| `client.refunds` | `create`, `retrieve`, `list` |
+| `client.transfers` | `create`, `retrieve`, `list` |
+| `client.beneficiaries` | `create`, `retrieve`, `update`, `delete`, `list` |
+| `client.links` | `create`, `retrieve`, `update`, `delete`, `list` |
+| `client.invoices` | `create`, `retrieve`, `update`, `delete`, `list`, `send`, `mark_paid`, `cancel` |
+| `client.accounts` | `create`, `retrieve`, `update`, `delete`, `list`, `regenerate_token` |
+| `client.webhook_endpoints` | `create`, `retrieve`, `update`, `delete`, `list`, `rotate_secret` |
+| `client.balance` | `retrieve` |
+| `client.events` | `list`, `retrieve`, `resend` |
+| `client.disputes` | `list`, `retrieve`, `submit_evidence`, `accept`, `close`, `send_message` |
+| `client.identity` | `resolve`, `validate` |
+| `client.tax` | `get_settings`, `update_settings`, `rates`, `calculate`, `reports`, `list_codes`, `retrieve_code`, `list_registrations`, `create_registration`, `retrieve_registration`, `update_registration`, `delete_registration`, `jurisdictions`, `thresholds`, `threshold_alerts` |
+| `client.shield` | `get_settings`, `update_settings`, `stats`, `list_blocklist`, `add_to_blocklist`, `remove_from_blocklist` |
+| `client.listen` | `config`, `auth` |
+| `client.webhooks` | `construct_event` (local — no HTTP) |
+
+## Sync (Connect)
+
+```ruby
+client.payments.create(params, Wajub::RequestOptions.new(sync: 'acct_sync_ref'))
+```
+
+## Webhooks
+
+```ruby
+begin
+  event = client.webhooks.construct_event(
+    request.body.read,  # String — raw body bytes
+    request.env['HTTP_X_WAJUB_SIGNATURE'],
+    request.env['HTTP_X_WAJUB_TIMESTAMP']
+  )
+rescue Wajub::WebhookSignatureVerificationError
+  halt 400
+end
+
+case event['type']
+when 'payment.succeeded'
+  # fulfill order
+end
+```
+
+During local development, use the [Wajub CLI](https://github.com/wajubhq/wajub-cli) to forward webhooks to your machine.
+
+## Pagination
+
+```ruby
+page = client.payments.list('per_page' => 50)
+
+page.auto_paging_each do |payment|
+  puts "#{payment['id']} #{payment['status']}"
+end
+
+# Manual page control
+first = client.payments.list
+second = first.next_page if first.has_more
+```
+
+## Idempotency
+
+POST and PUT requests automatically receive an `Idempotency-Key` header. Pass your own:
+
+```ruby
+client.payments.create(
+  params,
+  Wajub::RequestOptions.new(idempotency_key: "order-#{order_id}")
+)
+```
+
+## Error handling
+
+```ruby
+begin
+  client.payments.create(params)
+rescue Wajub::InvalidRequestError => e
+  puts e.errors   # field-level validation errors
+rescue Wajub::AuthenticationError
+  # 401 — bad API key
+rescue Wajub::RateLimitError
+  # 429 — back off and retry
+end
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+## Documentation & support
+
+- Full API reference: [docs.wajub.com/libraries/sdks/ruby](https://docs.wajub.com/libraries/sdks/ruby)
+- Report issues: [github.com/wajubhq/wajub-ruby/issues](https://github.com/wajubhq/wajub-ruby/issues)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/wajub/client.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative 'http/http_utils'
+require_relative 'http/base_client'
+require_relative 'resources'
+require_relative 'webhooks'
+
+module Wajub
+  class Client
+    attr_reader :global, :payments, :customers, :refunds, :transfers, :beneficiaries,
+                :links, :balance, :events, :accounts, :webhook_endpoints, :invoices,
+                :disputes, :identity, :tax, :shield, :listen, :webhooks
+
+    def initialize(api_key: nil, webhook_secret: nil, idempotency_key_prefix: 'wajub', transport: nil)
+      key = HttpUtils.normalize_api_key(api_key || ENV.fetch('WAJUB_API_KEY', ''))
+      raise ArgumentError, 'Wajub: api_key is required' if key.empty?
+
+      base_url = HttpUtils.api_url
+      prefix = idempotency_key_prefix
+      @transport = transport
+
+      @global = GlobalResource.new(key, base_url, prefix, transport: shared_transport(base_url))
+      @payments = PaymentsResource.new(key, base_url, prefix, transport: shared_transport(base_url))
+      @customers = CustomersResource.new(key, base_url, prefix, transport: shared_transport(base_url))
+      @refunds = CrudResource.new(key, base_url, 'refunds', 'refund', 'refunds', prefix, transport: shared_transport(base_url))
+      @transfers = CrudResource.new(key, base_url, 'transfers', 'transfer', 'transfers', prefix, transport: shared_transport(base_url))
+      @beneficiaries = CrudResource.new(key, base_url, 'beneficiaries', 'beneficiary', 'beneficiaries', prefix, transport: shared_transport(base_url))
+      @links = CrudResource.new(key, base_url, 'links', 'link', 'links', prefix, transport: shared_transport(base_url))
+      @balance = BalanceResource.new(key, base_url, prefix, transport: shared_transport(base_url))
+      @events = EventsResource.new(key, base_url, prefix, transport: shared_transport(base_url))
+      @accounts = AccountsResource.new(key, base_url, prefix, transport: shared_transport(base_url))
+      @webhook_endpoints = WebhookEndpointsResource.new(key, base_url, prefix, transport: shared_transport(base_url))
+      @invoices = InvoicesResource.new(key, base_url, prefix, transport: shared_transport(base_url))
+      @disputes = DisputesResource.new(key, base_url, prefix, transport: shared_transport(base_url))
+      @identity = IdentityResource.new(key, base_url, prefix, transport: shared_transport(base_url))
+      @tax = TaxResource.new(key, base_url, prefix, transport: shared_transport(base_url))
+      @shield = ShieldResource.new(key, base_url, prefix, transport: shared_transport(base_url))
+      @listen = ListenResource.new(key, base_url, prefix, transport: shared_transport(base_url))
+      @webhooks = Webhooks.new(webhook_secret || ENV.fetch('WAJUB_WEBHOOK_SECRET', ''))
+    end
+
+    private
+
+    def shared_transport(base_url)
+      @transport || @shared ||= NetHttpTransport.new(base_url, user_agent: "wajub-ruby/#{VERSION}")
+    end
+  end
+end

data/lib/wajub/crypto.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Wajub
+  module Crypto
+    module_function
+
+    def hmac_sha256(key, data)
+      OpenSSL::HMAC.hexdigest('SHA256', key, data)
+    end
+
+    def timing_safe_equal(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      l = a.unpack('C*')
+      r = b.unpack('C*')
+      result = 0
+      l.zip(r) { |x, y| result |= x ^ y }
+      result.zero?
+    end
+  end
+end

data/lib/wajub/errors.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Wajub
+  class WajubError < StandardError
+    attr_reader :code, :http_status, :errors, :raw
+
+    def initialize(message, code:, http_status:, errors: nil, raw: nil)
+      super(message)
+      @code = code
+      @http_status = http_status
+      @errors = errors
+      @raw = raw
+    end
+  end
+
+  class AuthenticationError < WajubError; end
+  class PermissionError < WajubError; end
+  class NotFoundError < WajubError; end
+  class InvalidRequestError < WajubError; end
+
+  class RateLimitError < WajubError
+    attr_reader :retry_after
+
+    def initialize(message, code:, http_status:, errors: nil, raw: nil, retry_after: nil)
+      super(message, code: code, http_status: http_status, errors: errors, raw: raw)
+      @retry_after = retry_after
+    end
+  end
+
+  class ApiConnectionError < WajubError
+    def initialize(message, code: 'network_error', http_status: 0, errors: nil, raw: nil)
+      super(message, code: code, http_status: http_status, errors: errors, raw: raw)
+    end
+  end
+
+  class WebhookSignatureVerificationError < StandardError; end
+
+  module Errors
+    module_function
+
+    def from_response(status, body, retry_after: nil)
+      message = body['message'] || "Request failed (#{status})"
+      code = body['error_code'] || body['code'] || "http_#{status}"
+      field_errors = parse_field_errors(body['errors'])
+
+      case status
+      when 401 then AuthenticationError.new(message, code: code, http_status: status, errors: field_errors, raw: body)
+      when 403 then PermissionError.new(message, code: code, http_status: status, errors: field_errors, raw: body)
+      when 404 then NotFoundError.new(message, code: code, http_status: status, errors: field_errors, raw: body)
+      when 429 then RateLimitError.new(message, code: code, http_status: status, errors: field_errors, raw: body, retry_after: retry_after)
+      when 400, 422 then InvalidRequestError.new(message, code: code, http_status: status, errors: field_errors, raw: body)
+      else WajubError.new(message, code: code, http_status: status, errors: field_errors, raw: body)
+      end
+    end
+
+    def parse_field_errors(raw)
+      return nil unless raw.is_a?(Hash)
+
+      raw.transform_values do |value|
+        value.is_a?(Array) ? value.first.to_s : value.to_s
+      end
+    end
+  end
+end

data/lib/wajub/http/base_client.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+require_relative 'http_utils'
+require_relative 'retry_policy'
+require_relative '../errors'
+require_relative '../request_options'
+require_relative '../version'
+
+module Wajub
+  class BaseClient
+    attr_reader :api_key, :base_url, :idempotency_key_prefix, :transport, :last_request
+
+    def initialize(api_key, base_url, idempotency_key_prefix = 'wajub', transport: nil)
+      @api_key = HttpUtils.normalize_api_key(api_key)
+      @base_url = base_url.sub(%r{/+\z}, '')
+      @idempotency_key_prefix = idempotency_key_prefix
+      @transport = transport || NetHttpTransport.new(@base_url, user_agent: "wajub-ruby/#{VERSION}")
+      @last_request = nil
+    end
+
+    def get(path, params = nil)
+      request('GET', path, body: nil, options: nil, query: params)
+    end
+
+    def post(path, body = nil, options = nil)
+      request('POST', path, body: body, options: options)
+    end
+
+    def put(path, body = nil, options = nil)
+      request('PUT', path, body: body, options: options)
+    end
+
+    def delete(path, options = nil)
+      request('DELETE', path, body: nil, options: options)
+    end
+
+    def request(method, path, body: nil, options: nil, query: nil)
+      headers = {
+        'Accept' => 'application/json',
+        'Authorization' => @api_key
+      }
+
+      options ||= RequestOptions.new
+      headers.merge!(options.headers) if options.headers
+      headers['X-Sync'] = options.sync if options.sync
+
+      idempotency_key = options.idempotency_key
+      if idempotency_key.nil? && !%w[GET DELETE].include?(method)
+        idempotency_key = HttpUtils.create_idempotency_key(@idempotency_key_prefix)
+      end
+      headers['Idempotency-Key'] = idempotency_key if idempotency_key
+
+      payload = body.nil? ? nil : JSON.generate(body)
+      headers['Content-Type'] = 'application/json' if payload
+
+      attempt = 0
+
+      loop do
+        begin
+          response = @transport.call(
+            method: method,
+            path: path,
+            headers: headers,
+            body: payload,
+            query: query
+          )
+        rescue StandardError => e
+          if attempt < RetryPolicy.max_retries
+            attempt += 1
+            sleep RetryPolicy.delay_seconds(attempt)
+            next
+          end
+          raise ApiConnectionError.new(e.message)
+        end
+
+        @last_request = response[:request]
+        status = response[:status]
+        data = response[:body].is_a?(Hash) ? response[:body] : HttpUtils.decode_json(response[:body].to_s)
+
+        return data if status >= 200 && status < 300
+
+        if RetryPolicy.should_retry_status?(status) && attempt < RetryPolicy.max_retries
+          attempt += 1
+          sleep RetryPolicy.delay_seconds(attempt, response: response[:headers] || {})
+          next
+        end
+
+        retry_after = response.dig(:headers, 'retry-after')&.to_i
+        raise Errors.from_response(status, data, retry_after: retry_after)
+      end
+    end
+  end
+
+  class NetHttpTransport
+    def initialize(base_url, user_agent:)
+      @base_url = base_url
+      @user_agent = user_agent
+      @mutex = Mutex.new
+    end
+
+    def call(method:, path:, headers:, body:, query:)
+      uri = URI.parse("#{@base_url}#{path}")
+      if query
+        filtered = query.compact
+        uri.query = URI.encode_www_form(filtered) unless filtered.empty?
+      end
+
+      http = connection(uri)
+
+      klass = Net::HTTP.const_get(method.capitalize)
+      request = klass.new(uri)
+      headers.each { |k, v| request[k] = v }
+      request['User-Agent'] = @user_agent
+      request.body = body if body
+
+      response = http.request(request)
+      {
+        status: response.code.to_i,
+        body: HttpUtils.decode_json(response.body),
+        headers: response.to_hash.transform_values(&:first),
+        request: {
+          method: method,
+          path: path,
+          uri: uri.to_s,
+          headers: headers.merge('User-Agent' => @user_agent)
+        }
+      }
+    end
+
+    private
+
+    # Reuses a single keep-alive Net::HTTP connection across calls (instead of
+    # opening a fresh TCP+TLS connection per request) since every call on this
+    # transport targets the same host/port (derived from @base_url).
+    def connection(uri)
+      @mutex.synchronize do
+        if @http && !@http.started?
+          @http = nil
+        end
+
+        @http ||= begin
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == 'https'
+          http.open_timeout = 30
+          http.read_timeout = 30
+          http.start
+          http
+        end
+      end
+    end
+  end
+
+  class MockTransport
+    attr_reader :last_request
+
+    def initialize(responses)
+      @responses = responses
+      @index = 0
+      @last_request = nil
+    end
+
+    def call(method:, path:, headers:, body:, query:)
+      @last_request = { method: method, path: path, headers: headers, body: body, query: query }
+      response = @responses[@index] || { status: 200, body: {} }
+      @index += 1
+      response.merge(request: @last_request)
+    end
+  end
+end

data/lib/wajub/http/http_utils.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require 'json'
+
+module Wajub
+  module HttpUtils
+    module_function
+
+    def normalize_api_key(raw)
+      key = raw.to_s.strip
+      key = key.sub(/\Abearer\s+/i, '').strip if key.match?(/\Abearer\s+/i)
+      key
+    end
+
+    def api_url
+      API_URL
+    end
+
+    def create_idempotency_key(prefix = 'wajub')
+      "#{prefix}-#{SecureRandom.uuid}"
+    end
+
+    def pick_resource(body, *keys)
+      keys.each do |key|
+        return body[key] if body.key?(key) && !body[key].nil?
+      end
+      body
+    end
+
+    def pick_list(body, *keys)
+      keys.each do |key|
+        if body.key?(key) && !body[key].nil?
+          return { data: body[key], meta: body['meta'] }
+        end
+      end
+      if body.key?('items') && !body['items'].nil?
+        return { data: body['items'], meta: body['meta'] }
+      end
+      { data: body['data'] || [], meta: body['meta'] }
+    end
+
+    def decode_json(data)
+      JSON.parse(data)
+    rescue JSON::ParserError
+      {}
+    end
+  end
+end

data/lib/wajub/http/retry_policy.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Wajub
+  module RetryPolicy
+    MAX_RETRIES = 2
+    RETRYABLE = [429, 500, 502, 503, 504].freeze
+
+    module_function
+
+    def should_retry_status?(status)
+      RETRYABLE.include?(status)
+    end
+
+    def max_retries
+      MAX_RETRIES
+    end
+
+    def delay_seconds(attempt, response: nil)
+      header = response&.[]('retry-after')&.strip
+      if header && !header.empty?
+        seconds = Integer(header, exception: false)
+        return seconds if seconds
+
+        time = Time.httpdate(header) rescue nil
+        return [(time - Time.now).to_i, 0].max if time
+      end
+
+      0.5 * (2**(attempt - 1))
+    end
+  end
+end

data/lib/wajub/objects.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Wajub
+  class ApiObject
+    def initialize(data)
+      @data = data.transform_keys(&:to_s)
+    end
+
+    def [](key)
+      @data[key.to_s]
+    end
+
+    def to_h
+      @data.dup
+    end
+
+    def method_missing(name, *args)
+      return super if args.any? || name.end_with?('=')
+
+      key = name.to_s
+      return @data[key] if @data.key?(key)
+
+      super
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @data.key?(name.to_s) || super
+    end
+  end
+
+  class Payment < ApiObject
+    def id
+      self['id']
+    end
+
+    def status
+      self['status']
+    end
+
+    def authorization_url
+      self['authorization_url']
+    end
+
+    def authorization_token
+      self['authorization_token']
+    end
+  end
+end

data/lib/wajub/pagination.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Wajub
+  class PagedResult
+    attr_reader :data, :meta, :has_more
+
+    def initialize(data:, meta:, has_more:, fetch_page:)
+      @data = data
+      @meta = meta
+      @has_more = has_more
+      @fetch_page = fetch_page
+    end
+
+    def next_page
+      raise WajubError.new('no more pages available', code: 'pagination_error', http_status: 0) unless @has_more
+
+      current = @meta&.fetch('current_page', 1).to_i
+      @fetch_page.call(current + 1)
+    end
+
+    def auto_paging_each(&block)
+      page = self
+      loop do
+        page.data.each(&block)
+        break unless page.has_more
+
+        page = page.next_page
+      end
+    end
+
+    def self.create(client, path, plural_key, params = nil)
+      params ||= {}
+      fetch = lambda do |page_num|
+        query = params.merge('page' => page_num)
+        res = client.get(path, query)
+        list = HttpUtils.pick_list(res, plural_key)
+        meta = list[:meta]
+        has_more = false
+        if meta
+          current = meta['current_page'].to_i
+          last = meta['last_page'].to_i
+          has_more = current < last if current.positive? && last.positive?
+        end
+        new(data: list[:data], meta: meta, has_more: has_more, fetch_page: fetch)
+      end
+
+      page = params['page'] || params[:page] || 1
+      fetch.call(page.to_i)
+    end
+  end
+end

data/lib/wajub/request_options.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Wajub
+  class RequestOptions
+    attr_reader :idempotency_key, :headers, :sync
+
+    def initialize(idempotency_key: nil, headers: nil, sync: nil)
+      @idempotency_key = idempotency_key
+      @headers = headers || {}
+      @sync = sync
+    end
+  end
+end

data/lib/wajub/resources.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+require_relative 'http/base_client'
+require_relative 'http/http_utils'
+require_relative 'pagination'
+
+module Wajub
+  class CrudResource < BaseClient
+    def initialize(api_key, base_url, path, singular, plural, idempotency_key_prefix = 'wajub', transport: nil)
+      super(api_key, base_url, idempotency_key_prefix, transport: transport)
+      @path = path
+      @singular = singular
+      @plural = plural
+    end
+
+    def create(params, options = nil)
+      HttpUtils.pick_resource(post("/#{@path}", params, options), @singular)
+    end
+
+    def retrieve(id)
+      HttpUtils.pick_resource(get("/#{@path}/#{URI.encode_www_form_component(id)}"), @singular)
+    end
+
+    def list(params = nil)
+      PagedResult.create(self, "/#{@path}", @plural, params)
+    end
+
+    def update(id, params, options = nil)
+      HttpUtils.pick_resource(put("/#{@path}/#{URI.encode_www_form_component(id)}", params, options), @singular)
+    end
+
+    def delete(id, options = nil)
+      request('DELETE', "/#{@path}/#{URI.encode_www_form_component(id)}", options: options)
+    end
+  end
+
+  class PaymentsResource < BaseClient
+    def create(params, options = nil)
+      to_payment_object(post('/payments', params, options))
+    end
+
+    def initialize_payment(params, options = nil)
+      create(params, options)
+    end
+
+    def retrieve(id)
+      res = get("/payments/#{URI.encode_www_form_component(id)}")
+      to_payment_object('transaction' => HttpUtils.pick_resource(res, 'transaction'))
+    end
+
+    def list(params = nil)
+      PagedResult.create(self, '/payments', 'transactions', params)
+    end
+
+    def cancel(id, options = nil)
+      res = delete("/payments/#{URI.encode_www_form_component(id)}", options)
+      to_payment_object('transaction' => HttpUtils.pick_resource(res, 'transaction'))
+    end
+
+    def process(id, params, options = nil)
+      res = post("/payments/#{URI.encode_www_form_component(id)}", params, options)
+      to_payment_object('transaction' => HttpUtils.pick_resource(res, 'transaction'))
+    end
+
+    def process_split(id, params, options = nil)
+      res = post("/payments/#{URI.encode_www_form_component(id)}/splits", params, options)
+      to_payment_object('transaction' => HttpUtils.pick_resource(res, 'transaction'))
+    end
+
+    def list_refunds(id, params = nil)
+      list = HttpUtils.pick_list(get("/payments/#{URI.encode_www_form_component(id)}/refunds", params), 'refunds')
+      [list[:data], list[:meta]]
+    end
+
+    private
+
+    def to_payment_object(body)
+      transaction = HttpUtils.pick_resource(body, 'transaction')
+      Payment.new(
+        transaction.merge(
+          'authorization_token' => body['authorization_token'] || transaction['authorization_token'] || transaction['id'],
+          'authorization_url' => body['authorization_url'] || transaction['authorization_url'] || ''
+        )
+      )
+    end
+  end
+
+  class GlobalResource < BaseClient
+    def ping
+      get('/')
+    end
+
+    def channels(params = nil)
+      list = HttpUtils.pick_list(get('/channels', params), 'channels')
+      [list[:data], list[:meta]]
+    end
+
+    def countries(params = nil)
+      list = HttpUtils.pick_list(get('/countries', params), 'countries')
+      [list[:data], list[:meta]]
+    end
+
+    def currencies(params = nil)
+      list = HttpUtils.pick_list(get('/currencies', params), 'currencies')
+      [list[:data], list[:meta]]
+    end
+  end
+
+  class BalanceResource < BaseClient
+    def retrieve
+      HttpUtils.pick_resource(get('/balance'), 'balance', 'data')
+    end
+  end
+
+  class EventsResource < BaseClient
+    def list(params = nil)
+      PagedResult.create(self, '/events', 'events', params)
+    end
+
+    def retrieve(id)
+      HttpUtils.pick_resource(get("/events/#{URI.encode_www_form_component(id)}"), 'event')
+    end
+
+    def resend(id, options = nil)
+      HttpUtils.pick_resource(post("/events/#{URI.encode_www_form_component(id)}/resend", nil, options), 'event')
+    end
+  end
+
+  class CustomersResource < CrudResource
+    def initialize(api_key, base_url, idempotency_key_prefix = 'wajub', transport: nil)
+      super(api_key, base_url, 'customers', 'customer', 'customers', idempotency_key_prefix, transport: transport)
+    end
+
+    def block(id, params = nil, options = nil)
+      HttpUtils.pick_resource(post("/customers/#{URI.encode_www_form_component(id)}/block", params, options), 'customer')
+    end
+
+    def unblock(id, options = nil)
+      HttpUtils.pick_resource(post("/customers/#{URI.encode_www_form_component(id)}/unblock", nil, options), 'customer')
+    end
+
+    def activate(id, options = nil)
+      HttpUtils.pick_resource(post("/customers/#{URI.encode_www_form_component(id)}/activate", nil, options), 'customer')
+    end
+
+    def deactivate(id, options = nil)
+      HttpUtils.pick_resource(post("/customers/#{URI.encode_www_form_component(id)}/deactivate", nil, options), 'customer')
+    end
+
+    def list_tax_ids(customer_id)
+      list = HttpUtils.pick_list(get("/customers/#{URI.encode_www_form_component(customer_id)}/tax_ids"), 'tax_ids')
+      [list[:data], list[:meta]]
+    end
+
+    def create_tax_id(customer_id, params, options = nil)
+      HttpUtils.pick_resource(post("/customers/#{URI.encode_www_form_component(customer_id)}/tax_ids", params, options), 'tax_id')
+    end
+
+    def delete_tax_id(customer_id, tax_id, options = nil)
+      delete("/customers/#{URI.encode_www_form_component(customer_id)}/tax_ids/#{URI.encode_www_form_component(tax_id)}", options)
+    end
+  end
+
+  class AccountsResource < CrudResource
+    def initialize(api_key, base_url, idempotency_key_prefix = 'wajub', transport: nil)
+      super(api_key, base_url, 'accounts', 'account', 'accounts', idempotency_key_prefix, transport: transport)
+    end
+
+    def regenerate_token(id, options = nil)
+      HttpUtils.pick_resource(post("/accounts/#{URI.encode_www_form_component(id)}/token", nil, options), 'account')
+    end
+  end
+
+  class WebhookEndpointsResource < CrudResource
+    def initialize(api_key, base_url, idempotency_key_prefix = 'wajub', transport: nil)
+      super(api_key, base_url, 'webhooks', 'endpoint', 'endpoints', idempotency_key_prefix, transport: transport)
+    end
+
+    def rotate_secret(id, options = nil)
+      HttpUtils.pick_resource(post("/webhooks/#{URI.encode_www_form_component(id)}/rotate-secret", nil, options), 'endpoint')
+    end
+  end
+
+  class InvoicesResource < CrudResource
+    def initialize(api_key, base_url, idempotency_key_prefix = 'wajub', transport: nil)
+      super(api_key, base_url, 'invoices', 'invoice', 'invoices', idempotency_key_prefix, transport: transport)
+    end
+
+    def send(id, options = nil)
+      HttpUtils.pick_resource(post("/invoices/#{URI.encode_www_form_component(id)}/send", nil, options), 'invoice')
+    end
+
+    def mark_paid(id, params = nil, options = nil)
+      HttpUtils.pick_resource(post("/invoices/#{URI.encode_www_form_component(id)}/mark-paid", params, options), 'invoice')
+    end
+
+    def cancel(id, options = nil)
+      HttpUtils.pick_resource(post("/invoices/#{URI.encode_www_form_component(id)}/cancel", nil, options), 'invoice')
+    end
+  end
+
+  class DisputesResource < BaseClient
+    def list(params = nil)
+      PagedResult.create(self, '/disputes', 'disputes', params)
+    end
+
+    def retrieve(id)
+      HttpUtils.pick_resource(get("/disputes/#{URI.encode_www_form_component(id)}"), 'dispute')
+    end
+
+    def submit_evidence(id, params, options = nil)
+      HttpUtils.pick_resource(post("/disputes/#{URI.encode_www_form_component(id)}/submit-evidence", params, options), 'dispute')
+    end
+
+    def accept(id, options = nil)
+      HttpUtils.pick_resource(post("/disputes/#{URI.encode_www_form_component(id)}/accept", nil, options), 'dispute')
+    end
+
+    def close(id, options = nil)
+      HttpUtils.pick_resource(post("/disputes/#{URI.encode_www_form_component(id)}/close", nil, options), 'dispute')
+    end
+
+    def send_message(id, params, options = nil)
+      HttpUtils.pick_resource(post("/disputes/#{URI.encode_www_form_component(id)}/messages", params, options), 'dispute')
+    end
+  end
+
+  class IdentityResource < BaseClient
+    def resolve(params, options = nil)
+      HttpUtils.pick_resource(post('/identity/resolve', params, options), 'identity')
+    end
+
+    def validate(params, options = nil)
+      HttpUtils.pick_resource(post('/identity/validate', params, options), 'identity')
+    end
+  end
+
+  class TaxResource < BaseClient
+    def get_settings
+      HttpUtils.pick_resource(get('/tax/settings'), 'tax', 'settings')
+    end
+
+    def update_settings(params, options = nil)
+      HttpUtils.pick_resource(put('/tax/settings', params, options), 'tax', 'settings')
+    end
+
+    def rates(params = nil)
+      list = HttpUtils.pick_list(get('/tax/rates', params), 'rates', 'tax_rates')
+      [list[:data], list[:meta]]
+    end
+
+    def calculate(params, options = nil)
+      HttpUtils.pick_resource(post('/tax/calculate', params, options), 'tax', 'calculation')
+    end
+  end
+
+  class ShieldResource < BaseClient
+    def get_settings
+      HttpUtils.pick_resource(get('/shield/settings'), 'shield', 'settings')
+    end
+
+    def update_settings(params, options = nil)
+      HttpUtils.pick_resource(put('/shield/settings', params, options), 'shield', 'settings')
+    end
+
+    def stats(params = nil)
+      HttpUtils.pick_resource(get('/shield/stats', params), 'shield', 'stats')
+    end
+  end
+
+  class ListenResource < BaseClient
+    def config
+      HttpUtils.pick_resource(get('/listen/config'), 'config', 'listen')
+    end
+
+    def auth(params, options = nil)
+      HttpUtils.pick_resource(post('/listen/auth', params, options), 'auth', 'listen')
+    end
+  end
+end

data/lib/wajub/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Wajub
+  VERSION = '1.1.0'
+  API_URL = 'https://api.wajub.com'
+end

data/lib/wajub/webhooks.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'crypto'
+require_relative 'errors'
+
+module Wajub
+  class Webhooks
+    DEFAULT_TOLERANCE = 300
+
+    attr_reader :secret
+
+    def initialize(secret)
+      @secret = secret.to_s
+    end
+
+    def construct_event(payload, signature, timestamp, tolerance = DEFAULT_TOLERANCE)
+      raise ArgumentError, 'Wajub: webhook_secret is required for construct_event' if @secret.empty?
+      raise WebhookSignatureVerificationError, 'Invalid webhook signature format. Expected v1={hash}.' unless signature.start_with?('v1=')
+      raise ArgumentError, 'Wajub: payload must be the raw request body as a String, not a parsed object' unless payload.is_a?(String)
+
+      body = payload
+      expected = Crypto.hmac_sha256(@secret, "#{timestamp}.#{body}")
+      received = signature.delete_prefix('v1=')
+
+      raise WebhookSignatureVerificationError, 'Webhook signature verification failed.' unless Crypto.timing_safe_equal(expected, received)
+
+      ts = Float(timestamp)
+      raise WebhookSignatureVerificationError, 'Invalid webhook timestamp.' unless ts.finite?
+
+      drift = (Time.now.to_i - ts).abs
+      if tolerance.positive? && drift > tolerance
+        raise WebhookSignatureVerificationError,
+              "Timestamp outside tolerance zone (#{drift.to_i}s drift, allowed #{tolerance}s)."
+      end
+
+      event = JSON.parse(body)
+      raise WebhookSignatureVerificationError, 'Invalid webhook payload JSON.' unless event.is_a?(Hash)
+
+      event
+    end
+  end
+end

data/lib/wajub.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'wajub/version'
+require_relative 'wajub/errors'
+require_relative 'wajub/request_options'
+require_relative 'wajub/objects'
+require_relative 'wajub/client'
+require_relative 'wajub/webhooks'
+
+module Wajub
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: wajub
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- Wajub
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Server-side Wajub payments, webhooks, and merchant API client.
+email:
+- hello@wajub.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/wajub.rb
+- lib/wajub/client.rb
+- lib/wajub/crypto.rb
+- lib/wajub/errors.rb
+- lib/wajub/http/base_client.rb
+- lib/wajub/http/http_utils.rb
+- lib/wajub/http/retry_policy.rb
+- lib/wajub/objects.rb
+- lib/wajub/pagination.rb
+- lib/wajub/request_options.rb
+- lib/wajub/resources.rb
+- lib/wajub/version.rb
+- lib/wajub/webhooks.rb
+homepage: https://docs.wajub.com/libraries/sdks/ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://docs.wajub.com/libraries/sdks/ruby
+  source_code_uri: https://github.com/wajubhq/wajub-ruby
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.17
+specification_version: 4
+summary: Official Wajub Ruby SDK
+test_files: []