tinker-pay-ruby-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b0b952007a71c15acfc412bf15ea914030bad28ff7d85fb947c64e81eb4e354d
+  data.tar.gz: 0c47365417e7520100310c3c87d9e0e72b28b7add64060a8a4c7bac300e93bff
+SHA512:
+  metadata.gz: 827689281ecc69e936adf6edf3ec4e63d7e5425310dc7e47405c2062c4ab2f807abf946a0de279c78f7f1d5308b72db29c56f8b9bb35adf115374bd3179e45d0
+  data.tar.gz: 6c9bab9ab2168427ac3c183dfce37c3560c9fc646e8e9439c0dbe700a4cbd2c0f83ca5ac785d7074b63f606d3a539ed4488e1ba8112c9bcf638f1324d7622949

data/.rspec_status

@@ -0,0 +1,31 @@
+example_id                                            | status | run_time        |
+----------------------------------------------------- | ------ | --------------- |
+./spec/integration/transaction_manager_spec.rb[1:1:1] | passed | 0.0268 seconds  |
+./spec/integration/transaction_manager_spec.rb[1:2:1] | passed | 0.00253 seconds |
+./spec/unit/config/configuration_spec.rb[1:1:1]       | passed | 0.00005 seconds |
+./spec/unit/config/configuration_spec.rb[1:2:1]       | passed | 0.00003 seconds |
+./spec/unit/enum/gateway_spec.rb[1:1]                 | passed | 0.00003 seconds |
+./spec/unit/enum/gateway_spec.rb[1:2]                 | passed | 0.00003 seconds |
+./spec/unit/enum/gateway_spec.rb[1:3]                 | passed | 0.00003 seconds |
+./spec/unit/enum/payment_status_spec.rb[1:1]          | passed | 0.00003 seconds |
+./spec/unit/enum/payment_status_spec.rb[1:2]          | passed | 0.00002 seconds |
+./spec/unit/enum/payment_status_spec.rb[1:3]          | passed | 0.00032 seconds |
+./spec/unit/enum/payment_status_spec.rb[1:4]          | passed | 0.00073 seconds |
+./spec/unit/model/transaction_spec.rb[1:1:1:1]        | passed | 0.00155 seconds |
+./spec/unit/model/transaction_spec.rb[1:1:2:1]        | passed | 0.00012 seconds |
+./spec/unit/model/transaction_spec.rb[1:2:1]          | passed | 0.0002 seconds  |
+./spec/unit/model/transaction_spec.rb[1:3:1]          | passed | 0.00005 seconds |
+./spec/unit/model/transaction_spec.rb[1:4:1]          | passed | 0.00009 seconds |
+./spec/unit/model/transaction_spec.rb[1:5:1]          | passed | 0.00008 seconds |
+./spec/unit/tinker_payments_spec.rb[1:1:1]            | passed | 0.00008 seconds |
+./spec/unit/tinker_payments_spec.rb[1:1:2]            | passed | 0.00013 seconds |
+./spec/unit/tinker_payments_spec.rb[1:2:1]            | passed | 0.0001 seconds  |
+./spec/unit/tinker_payments_spec.rb[1:2:2]            | passed | 0.00009 seconds |
+./spec/unit/tinker_payments_spec.rb[1:3:1]            | passed | 0.00009 seconds |
+./spec/unit/tinker_payments_spec.rb[1:3:2]            | passed | 0.00007 seconds |
+./spec/unit/webhook/webhook_handler_spec.rb[1:1:1]    | passed | 0.00013 seconds |
+./spec/unit/webhook/webhook_handler_spec.rb[1:1:2]    | passed | 0.00004 seconds |
+./spec/unit/webhook/webhook_handler_spec.rb[1:1:3]    | passed | 0.00154 seconds |
+./spec/unit/webhook/webhook_handler_spec.rb[1:1:4]    | passed | 0.00021 seconds |
+./spec/unit/webhook/webhook_handler_spec.rb[1:2:1]    | passed | 0.00014 seconds |
+./spec/unit/webhook/webhook_handler_spec.rb[1:2:2]    | passed | 0.00008 seconds |

data/.rubocop.yml

@@ -0,0 +1,64 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.0
+  Exclude:
+    - 'vendor/**/*'
+    - 'spec/spec_helper.rb'
+    - 'bin/**/*'
+    - 'tmp/**/*'
+    - '*.gemspec'
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Metrics/MethodLength:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/tinker/model/dto/**/*'
+    - 'lib/tinker/webhook/dto/**/*'
+    - 'lib/tinker/api/base_manager.rb'
+    - 'lib/tinker/auth/authentication_manager.rb'
+    - 'lib/tinker/model/transaction.rb'
+  Max: 15
+
+Metrics/AbcSize:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/tinker/model/dto/**/*'
+    - 'lib/tinker/webhook/dto/**/*'
+    - 'lib/tinker/api/base_manager.rb'
+    - 'lib/tinker/auth/authentication_manager.rb'
+    - 'lib/tinker/http/http_client.rb'
+  Max: 20
+
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - 'spec/**/*'
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Exclude:
+    - 'spec/**/*'
+  Max: 10
+
+Metrics/ParameterLists:
+  Exclude:
+    - 'lib/tinker/model/dto/**/*'
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'spec/**/*'
+
+Naming/FileName:
+  Exclude:
+    - 'lib/tinker.rb'
+

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'rspec', '~> 3.12'
+  gem 'rubocop', '~> 1.57', require: false
+  gem 'webmock', '~> 3.18'
+end

data/README.md

@@ -0,0 +1,166 @@
+# Tinker Payments Ruby SDK
+
+Official Ruby SDK for [Tinker Payments API](https://payments.tinker.co.ke/docs).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tinker-pay-ruby-sdk'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install tinker-pay-ruby-sdk
+```
+
+## Requirements
+
+- Ruby 3.0 or higher
+- No external runtime dependencies (uses standard library)
+
+## Quick Start
+
+```ruby
+require 'tinker'
+
+tinker = Tinker::Payments.new(
+  api_public_key: 'your-public-key',
+  api_secret_key: 'your-secret-key'
+)
+```
+
+## Usage
+
+### Initiate a Payment
+
+```ruby
+require 'tinker'
+
+begin
+  initiate_request = Tinker::Model::Dto::InitiatePaymentRequestDto.new(
+    amount: 100.00,
+    currency: 'KES',
+    gateway: Tinker::Enum::Gateway::MPESA,
+    merchant_reference: 'ORDER-12345',
+    return_url: 'https://your-app.com/payment/return',
+    customer_phone: '+254712345678',
+    transaction_desc: 'Payment for order #12345',
+    metadata: { order_id: '12345' }
+  )
+
+  transaction = tinker.transactions.initiate(initiate_request)
+  initiation_data = transaction.initiation_data
+
+  if initiation_data&.authorization_url
+    # Redirect user to authorization URL (Paystack, Stripe, etc.)
+    redirect_to initiation_data.authorization_url
+  end
+rescue Tinker::Exception::ApiException => e
+  puts "API Error: #{e.message}"
+rescue Tinker::Exception::NetworkException => e
+  puts "Network Error: #{e.message}"
+end
+```
+
+**Note:** The `return_url` is where users are redirected after payment completion. Webhooks are configured separately in your dashboard.
+
+### Query a Transaction
+
+```ruby
+query_request = Tinker::Model::Dto::QueryPaymentRequestDto.new(
+  payment_reference: 'TXN-abc123xyz',
+  gateway: Tinker::Enum::Gateway::MPESA
+)
+
+transaction = tinker.transactions.query(query_request)
+
+if transaction.successful?
+  query_data = transaction.query_data
+  puts "Amount: #{query_data.amount} #{query_data.currency}"
+end
+```
+
+### Handle Webhooks
+
+Webhooks support multiple event types: payment, subscription, invoice, and settlement. Check the event type and handle accordingly:
+
+```ruby
+require 'tinker'
+
+event = tinker.webhooks.handle_from_request(request.body.read)
+
+# Check event type
+if event.payment_event?
+  payment_data = event.payment_data
+  # Handle payment.completed, payment.failed, etc.
+elsif event.subscription_event?
+  subscription_data = event.subscription_data
+  # Handle subscription.created, subscription.cancelled, etc.
+elsif event.invoice_event?
+  invoice_data = event.invoice_data
+  # Handle invoice.paid, invoice.failed
+elsif event.settlement_event?
+  settlement_data = event.settlement_data
+  # Handle settlement.processed
+end
+
+# Access event details
+puts "Event type: #{event.type}"        # e.g., "payment.completed"
+puts "Event source: #{event.source}"    # e.g., "payment"
+puts "App ID: #{event.meta.app_id}"
+puts "Signature: #{event.security.signature}"
+```
+
+For payment events only, you can convert to a `Transaction` object:
+
+```ruby
+transaction = tinker.webhooks.handle_as_transaction(request.body.read)
+if transaction && transaction.successful?
+  callback_data = transaction.callback_data
+  puts "Payment successful: #{callback_data.reference}"
+end
+```
+
+## Custom HTTP Client
+
+You can use your own HTTP client by passing it to the constructor:
+
+```ruby
+require 'tinker'
+
+# Create a custom HTTP client that responds to #post(url, headers:, body:)
+# and returns an object with #status_code, #body, and #json methods
+custom_client = MyCustomHttpClient.new
+
+tinker = Tinker::Payments.new(
+  api_public_key: 'your-public-key',
+  api_secret_key: 'your-secret-key',
+  http_client: custom_client
+)
+```
+
+## Documentation
+
+For detailed API documentation, visit [Tinker Payments API Documentation](https://payments.tinker.co.ke/docs).
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake spec` to run the tests.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/tinker/payments-ruby-sdk.
+
+## License
+
+MIT License
+

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/tinker/api/base_manager.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Tinker
+  module Api
+    class BaseManager
+      def initialize(config:, http_client:, auth_manager:)
+        @config = config
+        @http_client = http_client
+        @auth_manager = auth_manager
+      end
+
+      protected
+
+      def request(_method, endpoint, data = {})
+        base_url = @config.base_url.chomp('/')
+        endpoint = endpoint[1..] if endpoint.start_with?('/')
+        url = "#{base_url}/#{endpoint}"
+
+        token = @auth_manager.token
+        headers = {
+          'Authorization' => "Bearer #{token}",
+          'Accept' => 'application/json',
+          'Content-Type' => 'application/json'
+        }
+
+        body = data.empty? ? nil : JSON.generate(data)
+
+        response = @http_client.post(url, headers: headers, body: body)
+        result = response.json
+
+        if response.status_code >= 400
+          message = result.is_a?(Hash) ? (result['message'] || result['error'] || 'Unknown error') : 'Unknown error'
+          raise Exception::ApiException.new(message, Exception::ExceptionCode::API_ERROR)
+        end
+
+        result || {}
+      rescue Exception::ApiException => e
+        raise e
+      rescue StandardError => e
+        raise Exception::NetworkException.new("Failed to communicate with Tinker API: #{e.message}",
+                                              Exception::ExceptionCode::NETWORK_ERROR, e)
+      end
+    end
+  end
+end

data/lib/tinker/api/transaction_manager.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Api
+    class TransactionManager < BaseManager
+      def initiate(request)
+        payload = request.to_hash
+        response = request('POST', Config::Endpoints::PAYMENT_INITIATE_PATH, payload)
+
+        Model::Transaction.new(response)
+      end
+
+      def query(request)
+        payload = request.to_hash
+        response = request('POST', Config::Endpoints::PAYMENT_QUERY_PATH, payload)
+
+        Model::Transaction.new(response)
+      end
+    end
+  end
+end

data/lib/tinker/auth/authentication_manager.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'uri'
+require 'json'
+
+module Tinker
+  module Auth
+    class AuthenticationManager
+      def initialize(config:, http_client:)
+        @config = config
+        @http_client = http_client
+        @token = nil
+        @expires_at = nil
+      end
+
+      def token
+        return @token if token_valid?
+
+        fetch_token
+      end
+
+      private
+
+      def token_valid?
+        return false if @token.nil? || @expires_at.nil?
+
+        Time.now.to_i < (@expires_at - 60)
+      end
+
+      def fetch_token
+        credentials = Base64.strict_encode64("#{@config.api_public_key}:#{@config.api_secret_key}")
+
+        url = Config::Endpoints::AUTH_TOKEN_URL
+        headers = {
+          'Content-Type' => 'application/x-www-form-urlencoded',
+          'Accept' => 'application/json'
+        }
+        body = "credentials=#{URI.encode_www_form_component(credentials)}"
+
+        response = @http_client.post(url, headers: headers, body: body)
+        result = response.json
+
+        if response.status_code >= 400
+          message = result['message'] || 'Authentication failed'
+          raise Exception::AuthenticationException.new(message, Exception::ExceptionCode::AUTHENTICATION_ERROR)
+        end
+
+        unless result['token']
+          raise Exception::NetworkException.new('Invalid authentication response: token missing', Exception::ExceptionCode::AUTHENTICATION_ERROR)
+        end
+
+        @token = result['token']
+        expires_in = result['expires_in'] || 3600
+        @expires_at = Time.now.to_i + expires_in
+
+        @token
+      rescue Exception::AuthenticationException, Exception::NetworkException => e
+        raise e
+      rescue StandardError => e
+        raise Exception::NetworkException.new("Failed to authenticate: #{e.message}",
+                                              Exception::ExceptionCode::AUTHENTICATION_ERROR, e)
+      end
+    end
+  end
+end

data/lib/tinker/config/configuration.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Config
+    class Configuration
+      attr_reader :api_public_key, :api_secret_key, :base_url
+
+      def initialize(api_public_key:, api_secret_key:)
+        @api_public_key = api_public_key
+        @api_secret_key = api_secret_key
+        @base_url = "#{Endpoints::API_BASE_URL}/"
+      end
+
+      def api_key
+        @api_secret_key
+      end
+    end
+  end
+end

data/lib/tinker/config/endpoints.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Config
+    class Endpoints
+      BASE_URL = 'https://payments.tinker.co.ke'
+      API_BASE_URL = "#{BASE_URL}/api".freeze
+      AUTH_TOKEN_URL = "#{BASE_URL}/auth/token".freeze
+      PAYMENT_INITIATE_PATH = '/payment/initiate'
+      PAYMENT_QUERY_PATH = '/payment/query'
+    end
+  end
+end

data/lib/tinker/enum/gateway.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Enum
+    class Gateway
+      MPESA = 'mpesa'
+      PAYSTACK = 'paystack'
+      STRIPE = 'stripe'
+    end
+  end
+end

data/lib/tinker/enum/payment_status.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Enum
+    class PaymentStatus
+      PENDING = 'pending'
+      SUCCESS = 'success'
+      CANCELLED = 'cancelled'
+      FAILED = 'failed'
+    end
+  end
+end

data/lib/tinker/exception/api_exception.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Exception
+    class ApiException < StandardError
+      def initialize(message, code = ExceptionCode::API_ERROR)
+        super(message)
+        @code = code
+      end
+
+      attr_reader :code
+    end
+  end
+end

data/lib/tinker/exception/authentication_exception.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Exception
+    class AuthenticationException < StandardError
+      def initialize(message, code = ExceptionCode::AUTHENTICATION_ERROR, previous = nil)
+        super(message)
+        @code = code
+        set_backtrace(previous.backtrace) if previous
+      end
+
+      attr_reader :code
+    end
+  end
+end

data/lib/tinker/exception/client_exception.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Exception
+    class ClientException < StandardError
+      def initialize(message, code = ExceptionCode::CLIENT_ERROR, previous = nil)
+        super(message)
+        @code = code
+        set_backtrace(previous.backtrace) if previous
+      end
+
+      attr_reader :code
+    end
+  end
+end

data/lib/tinker/exception/exception_code.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Exception
+    class ExceptionCode
+      API_ERROR = 1000
+      NETWORK_ERROR = 2000
+      AUTHENTICATION_ERROR = 3000
+      INVALID_PAYLOAD = 4000
+      WEBHOOK_ERROR = 5000
+      STREAM_ERROR = 6000
+      CLIENT_ERROR = 7000
+    end
+  end
+end

data/lib/tinker/exception/invalid_payload_exception.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Exception
+    class InvalidPayloadException < StandardError
+      def initialize(message, code = ExceptionCode::INVALID_PAYLOAD, previous = nil)
+        super(message)
+        @code = code
+        set_backtrace(previous.backtrace) if previous
+      end
+
+      attr_reader :code
+    end
+  end
+end

data/lib/tinker/exception/network_exception.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Exception
+    class NetworkException < StandardError
+      def initialize(message, code = ExceptionCode::NETWORK_ERROR, previous = nil)
+        super(message)
+        @code = code
+        set_backtrace(previous.backtrace) if previous
+      end
+
+      attr_reader :code
+    end
+  end
+end

data/lib/tinker/exception/webhook_exception.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Exception
+    class WebhookException < StandardError
+      def initialize(message, code = ExceptionCode::WEBHOOK_ERROR, previous = nil)
+        super(message)
+        @code = code
+        set_backtrace(previous.backtrace) if previous
+      end
+
+      attr_reader :code
+    end
+  end
+end

data/lib/tinker/http/http_client.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module Tinker
+  module Http
+    class HttpClient
+      def initialize
+        @timeout = 30
+      end
+
+      def post(url, headers: {}, body: nil)
+        uri = URI(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == 'https'
+        http.read_timeout = @timeout
+        http.open_timeout = @timeout
+
+        request = Net::HTTP::Post.new(uri.path)
+        headers.each { |key, value| request[key] = value }
+        request.body = body if body
+
+        response = http.request(request)
+        Response.new(response.code.to_i, response.body, response.to_hash)
+      rescue StandardError => e
+        raise Exception::NetworkException.new("Network error: #{e.message}", Exception::ExceptionCode::NETWORK_ERROR, e)
+      end
+
+      class Response
+        attr_reader :status_code, :body, :headers
+
+        def initialize(status_code, body, headers)
+          @status_code = status_code
+          @body = body
+          @headers = headers
+        end
+
+        def json
+          JSON.parse(@body)
+        rescue JSON::ParserError => e
+          raise Exception::InvalidPayloadException.new("Invalid JSON response: #{e.message}", Exception::ExceptionCode::INVALID_PAYLOAD)
+        end
+      end
+    end
+  end
+end