tinker-pay-ruby-sdk 0.1.0 → 0.6.0

data/lib/tinker/api/subscription_manager.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+module Tinker
+  module Api
+    class SubscriptionManager < BaseManager
+      def create_plan(request)
+        payload = request.to_hash
+        request('POST', Config::Endpoints::SUBSCRIPTION_PLANS_PATH, payload)
+      end
+
+      def list_plans
+        wrapped = request('GET', Config::Endpoints::SUBSCRIPTION_PLANS_PATH, nil)
+        wrapped['value'].is_a?(Array) ? wrapped['value'] : []
+      end
+
+      def update_plan(plan_id, request)
+        request('PUT', plan_path(plan_id), request.to_hash)
+      end
+
+      def delete_plan(plan_id)
+        request('DELETE', plan_path(plan_id), nil)
+      end
+
+      def list_invoices(subscription_id: nil, page: nil, page_size: nil)
+        query = URI.encode_www_form({ subscription_id: subscription_id, page: page, page_size: page_size }.compact)
+        path = Config::Endpoints::SUBSCRIPTION_INVOICES_PATH
+        request('GET', query.empty? ? path : "#{path}?#{query}", nil)
+      end
+
+      def create(request)
+        payload = request.to_hash
+        request('POST', Config::Endpoints::SUBSCRIPTION_BASE_PATH, payload)
+      end
+
+      def list(plan_id: nil, external_customer_id: nil)
+        endpoint = Config::Endpoints::SUBSCRIPTION_BASE_PATH
+        params = []
+        params << "plan_id=#{CGI.escape(plan_id)}" if plan_id && !plan_id.strip.empty?
+        if external_customer_id && !external_customer_id.strip.empty?
+          params << "external_customer_id=#{CGI.escape(external_customer_id)}"
+        end
+        endpoint += "?#{params.join('&')}" unless params.empty?
+
+        wrapped = request('GET', endpoint, nil)
+        wrapped['value'].is_a?(Array) ? wrapped['value'] : []
+      end
+
+      def cancel(subscription_id)
+        request('POST', "#{Config::Endpoints::SUBSCRIPTION_BASE_PATH}/#{subscription_id}/cancel", nil)
+      end
+
+      def checkout(request)
+        request('POST', 'merchant/billing/checkout', request.to_hash)
+      end
+
+      def expire_checkout(id, key)
+        request('POST', "merchant/billing/checkout/#{escape_path(id)}/expire", idempotency_key: key)
+      end
+
+      def billing_resource(id)
+        request('GET', billing_resource_path(id))
+      end
+
+      def change_quantity(id, quantity, key)
+        request('POST', "#{billing_resource_path(id)}/quantity", quantity: quantity, idempotency_key: key)
+      end
+
+      def schedule_quantity(id, quantity, key)
+        request('POST', "#{billing_resource_path(id)}/schedule", quantity: quantity, idempotency_key: key)
+      end
+
+      def clear_scheduled_quantity(id, key)
+        request('POST', "#{billing_resource_path(id)}/unschedule", idempotency_key: key)
+      end
+
+      def set_cancel_at_renewal(id, cancel, key)
+        request('POST', "#{billing_resource_path(id)}/cancel", cancel: cancel, idempotency_key: key)
+      end
+
+      def set_trial_end(id, end_time, key)
+        request('POST', "#{billing_resource_path(id)}/trial-end", trial_end: end_time.to_i, idempotency_key: key)
+      end
+
+      def end_trial(id, key)
+        request('POST', "#{billing_resource_path(id)}/end-trial", idempotency_key: key)
+      end
+
+      def billing_operation(key)
+        request('GET', "merchant/billing/operations/#{escape_path(key)}")
+      end
+
+      def payment_method_portal(id, return_url, key)
+        request('POST', "#{billing_resource_path(id)}/payment-method", return_url: return_url, idempotency_key: key)
+      end
+
+      def billing_payment_history(id, cursor = '', snapshot = 0)
+        params = {}
+        params['starting_after'] = cursor unless cursor.empty?
+        params['snapshot'] = snapshot if snapshot.positive?
+        endpoint = "#{billing_resource_path(id)}/payment-history"
+        endpoint += "?#{URI.encode_www_form(params)}" unless params.empty?
+        request('GET', endpoint)
+      end
+
+      private
+
+      def plan_path(id)
+        "#{Config::Endpoints::SUBSCRIPTION_PLANS_PATH}/#{escape_path(id)}"
+      end
+
+      def billing_resource_path(id)
+        "merchant/billing/resources/#{escape_path(id)}"
+      end
+
+      def escape_path(value)
+        URI.encode_www_form_component(value).gsub('+', '%20')
+      end
+    end
+  end
+end

data/lib/tinker/api/transaction_manager.rb

@@ -16,6 +16,39 @@ module Tinker
 
         Model::Transaction.new(response)
       end
+
+      def capabilities(currency: nil, country: nil)
+        query = URI.encode_www_form({ currency: currency, country: country }.compact)
+        path = Config::Endpoints::PAYMENT_CAPABILITIES_PATH
+        request('GET', query.empty? ? path : "#{path}?#{query}")
+      end
+
+      def refund(payment_id, payload, key)
+        result = request('POST', "#{payment_path(payment_id)}/refund", payload.to_hash, operation_headers(key))
+        Model::RefundResult.new(result)
+      end
+
+      def refunds(payment_id)
+        request('GET', "#{payment_path(payment_id)}/refunds")
+      end
+
+      def get_refund(payment_id, refund_id)
+        Model::Refund.new(request('GET', "#{payment_path(payment_id)}/refunds/#{resource_id(refund_id)}"))
+      end
+
+      def cancel_checkout(payment_id, payload, key)
+        result = request('POST', "#{payment_path(payment_id)}/cancellations", payload.to_hash, operation_headers(key))
+        Model::CancellationResult.new(result)
+      end
+
+      def cancellations(payment_id)
+        request('GET', "#{payment_path(payment_id)}/cancellations")
+      end
+
+      def get_cancellation(payment_id, request_id)
+        endpoint = "#{payment_path(payment_id)}/cancellations/#{resource_id(request_id)}"
+        Model::CheckoutCancellation.new(request('GET', endpoint))
+      end
     end
   end
 end

data/lib/tinker/auth/authentication_manager.rb

@@ -7,11 +7,14 @@ require 'json'
 module Tinker
   module Auth
     class AuthenticationManager
+      attr_reader :last_meta
+
       def initialize(config:, http_client:)
         @config = config
         @http_client = http_client
         @token = nil
         @expires_at = nil
+        @last_meta = nil
       end
 
       def token
@@ -31,27 +34,26 @@ module Tinker
       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)
+        response = @http_client.post(@config.auth_url, headers: headers, body: body)
         result = response.json
+        auth_data = extract_auth_data(result)
 
         if response.status_code >= 400
-          message = result['message'] || 'Authentication failed'
-          raise Exception::AuthenticationException.new(message, Exception::ExceptionCode::AUTHENTICATION_ERROR)
+          raise Exception::AuthenticationException.new(extract_error_message(result), Exception::ExceptionCode::AUTHENTICATION_ERROR)
         end
 
-        unless result['token']
+        unless auth_data['token']
           raise Exception::NetworkException.new('Invalid authentication response: token missing', Exception::ExceptionCode::AUTHENTICATION_ERROR)
         end
 
-        @token = result['token']
-        expires_in = result['expires_in'] || 3600
+        @token = auth_data['token']
+        expires_in = auth_data['expires_in'] || 3600
         @expires_at = Time.now.to_i + expires_in
 
         @token
@@ -61,6 +63,29 @@ module Tinker
         raise Exception::NetworkException.new("Failed to authenticate: #{e.message}",
                                               Exception::ExceptionCode::AUTHENTICATION_ERROR, e)
       end
+
+      def extract_auth_data(result)
+        if result.is_a?(Hash) && result.key?('success')
+          @last_meta = Model::ApiMeta.new(result['meta'] || {})
+          if result['success'] == false
+            raise Exception::AuthenticationException.new(extract_error_message(result), Exception::ExceptionCode::AUTHENTICATION_ERROR)
+          end
+
+          return result['data'].is_a?(Hash) ? result['data'] : {}
+        end
+
+        result.is_a?(Hash) ? result : {}
+      end
+
+      def extract_error_message(result)
+        if result.is_a?(Hash)
+          error = result['error']
+          return error['message'] || error['code'] || 'Authentication failed' if error.is_a?(Hash)
+
+          return result['message'] || 'Authentication failed'
+        end
+        'Authentication failed'
+      end
     end
   end
 end

data/lib/tinker/config/configuration.rb

@@ -3,17 +3,35 @@
 module Tinker
   module Config
     class Configuration
-      attr_reader :api_public_key, :api_secret_key, :base_url
+      attr_reader :api_public_key, :api_secret_key, :base_url, :auth_url
 
-      def initialize(api_public_key:, api_secret_key:)
+      def initialize(api_public_key:, api_secret_key:, base_url: nil)
         @api_public_key = api_public_key
         @api_secret_key = api_secret_key
-        @base_url = "#{Endpoints::API_BASE_URL}/"
+
+        resolved_base_url = base_url
+        if resolved_base_url.nil? || resolved_base_url.strip.empty?
+          resolved_base_url = sandbox_credentials? ? Endpoints::SANDBOX_BASE_URL : Endpoints::PRODUCTION_BASE_URL
+        end
+
+        resolved_base_url = resolved_base_url.chomp('/')
+        unless resolved_base_url.end_with?(Endpoints::API_VERSION_PATH)
+          resolved_base_url = "#{resolved_base_url}#{Endpoints::API_VERSION_PATH}"
+        end
+
+        @base_url = "#{resolved_base_url}/"
+        @auth_url = "#{resolved_base_url}#{Endpoints::AUTH_TOKEN_PATH}"
       end
 
       def api_key
         @api_secret_key
       end
+
+      private
+
+      def sandbox_credentials?
+        @api_public_key.start_with?('pk_test_') || @api_secret_key.start_with?('sk_test_')
+      end
     end
   end
 end

data/lib/tinker/config/endpoints.rb

@@ -3,11 +3,16 @@
 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'
+      PRODUCTION_BASE_URL = 'https://api.tinkerpayments.com'
+      SANDBOX_BASE_URL = 'https://sandbox-api.tinkerpayments.com'
+      API_VERSION_PATH = '/v1'
+      AUTH_TOKEN_PATH = '/auth/token'
+      PAYMENT_INITIATE_PATH = '/merchant/payment/initiate'
+      PAYMENT_QUERY_PATH = '/merchant/payment/query'
+      PAYMENT_CAPABILITIES_PATH = '/merchant/payment/capabilities'
+      SUBSCRIPTION_BASE_PATH = '/merchant/subscriptions'
+      SUBSCRIPTION_PLANS_PATH = '/merchant/subscriptions/plans'
+      SUBSCRIPTION_INVOICES_PATH = '/merchant/subscriptions/invoices'
     end
   end
 end

data/lib/tinker/enum/gateway.rb

@@ -6,6 +6,7 @@ module Tinker
       MPESA = 'mpesa'
       PAYSTACK = 'paystack'
       STRIPE = 'stripe'
+      PESAPAL = 'pesapal'
     end
   end
 end

data/lib/tinker/enum/payment_status.rb

@@ -4,9 +4,20 @@ module Tinker
   module Enum
     class PaymentStatus
       PENDING = 'pending'
+      AUTHORISED = 'authorised'
       SUCCESS = 'success'
       CANCELLED = 'cancelled'
       FAILED = 'failed'
+      BLOCKED = 'blocked'
+      REFUNDED = 'refunded'
+      PARTIALLY_REFUNDED = 'partially_refunded'
+      EXPIRED = 'expired'
+      REVERSED = 'reversed'
+
+      def self.parse(value)
+        value = (value || PENDING).to_s
+        value == 'completed' ? SUCCESS : value
+      end
     end
   end
 end

data/lib/tinker/exception/api_exception.rb

@@ -3,12 +3,28 @@
 module Tinker
   module Exception
     class ApiException < StandardError
-      def initialize(message, code = ExceptionCode::API_ERROR)
+      def initialize(message, code = ExceptionCode::API_ERROR, http_status: nil, details: nil, headers: {})
         super(message)
         @code = code
+        @http_status = http_status
+        @details = details
+        extract_metadata(details, headers)
       end
 
-      attr_reader :code
+      attr_reader :code, :http_status, :error_code, :provider_code, :request_id, :retry_after, :outcome, :details
+
+      private
+
+      def extract_metadata(details, headers)
+        error = details.is_a?(Hash) && details['error'].is_a?(Hash) ? details['error'] : {}
+        normalized_headers = headers.transform_keys { |key| key.to_s.downcase }
+        @error_code = error['code']
+        @provider_code = error['provider_code']
+        @request_id = error['request_id'] || Array(normalized_headers['x-request-id']).first
+        @retry_after = Array(normalized_headers['retry-after']).first
+        # Only an explicit not_applied confirms no mutation.
+        @outcome = error['outcome']
+      end
     end
   end
 end

data/lib/tinker/exception/feature_not_supported_exception.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Exception
+    class FeatureNotSupportedException < ApiException
+      CODE = 'FEATURE_NOT_SUPPORTED'
+
+      def gateway
+        error_details['gateway']
+      end
+
+      def feature
+        error_details['feature']
+      end
+
+      def alternatives
+        Array(error_details['alternatives'])
+      end
+
+      private
+
+      def error_details
+        error = @details.is_a?(Hash) ? @details['error'] : nil
+        error.is_a?(Hash) && error['details'].is_a?(Hash) ? error['details'] : {}
+      end
+    end
+  end
+end

data/lib/tinker/http/http_client.rb

@@ -11,18 +11,38 @@ module Tinker
         @timeout = 30
       end
 
+      def get(url, headers: {})
+        request(url, Net::HTTP::Get, headers: headers)
+      end
+
       def post(url, headers: {}, body: nil)
+        request(url, Net::HTTP::Post, headers: headers, body: body)
+      end
+
+      def put(url, headers: {}, body: nil)
+        request(url, Net::HTTP::Put, headers: headers, body: body)
+      end
+
+      def delete(url, headers: {}, body: nil)
+        request(url, Net::HTTP::Delete, headers: headers, body: body)
+      end
+
+      private
+
+      def request(url, request_class, 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
+        path = uri.path
+        path += "?#{uri.query}" if uri.query
+        req = request_class.new(path)
+        headers.each { |key, value| req[key] = value }
+        req.body = body if body
 
-        response = http.request(request)
+        response = http.request(req)
         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)

data/lib/tinker/model/api_meta.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Model
+    class ApiMeta
+      attr_reader :request_id, :timestamp, :environment
+
+      def initialize(meta = {})
+        @request_id = meta['request_id']
+        @timestamp = meta['timestamp']
+        @environment = meta['environment']
+      end
+
+      def to_hash
+        {
+          request_id: @request_id,
+          timestamp: @timestamp,
+          environment: @environment
+        }
+      end
+    end
+  end
+end

data/lib/tinker/model/cancellation_result.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Model
+    class CancellationResult
+      attr_reader :cancellation, :replayed
+
+      def initialize(data)
+        @cancellation = CheckoutCancellation.new(data.fetch('cancellation'))
+        @replayed = data['replayed'] == true
+      end
+    end
+  end
+end

data/lib/tinker/model/checkout_cancellation.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Model
+    class CheckoutCancellation < LifecycleResource
+    end
+  end
+end

data/lib/tinker/model/dto/callback_data_dto.rb

@@ -4,22 +4,18 @@ module Tinker
   module Model
     module Dto
       class CallbackDataDto
-        attr_reader :id, :status, :reference, :amount, :currency, :paid_at, :created_at, :channel
+        attr_reader :id, :status, :reference, :amount, :currency, :paid_at, :created_at, :channel, :country
 
         def initialize(data)
           @id = data['id']
-          status_value = data['status'] || 'pending'
-          @status = begin
-            Tinker::Enum::PaymentStatus.const_get(status_value.upcase)
-          rescue NameError
-            Tinker::Enum::PaymentStatus::PENDING
-          end
+          @status = Tinker::Enum::PaymentStatus.parse(data['status'])
           @reference = data['reference']
           @amount = data['amount'].to_f
           @currency = data['currency']
           @paid_at = data['paid_at']
           @created_at = data['created_at']
           @channel = data['channel']
+          @country = data['country']
         end
 
         def to_hash
@@ -32,7 +28,7 @@ module Tinker
             paid_at: @paid_at,
             created_at: @created_at,
             channel: @channel
-          }
+          }.merge(@country ? { country: @country } : {})
         end
       end
     end

data/lib/tinker/model/dto/cancellation_request.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Model
+    module Dto
+      class CancellationRequest
+        def initialize(reason:)
+          @payload = { reason: reason }
+        end
+
+        def to_hash
+          @payload.dup
+        end
+      end
+    end
+  end
+end

data/lib/tinker/model/dto/create_subscription_plan_request_dto.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Model
+    module Dto
+      class CreateSubscriptionPlanRequestDto
+        def initialize(name:, amount:, currency:, intervals:, description: '', is_active: true, features_json: nil)
+          @name = name
+          @amount = amount
+          @currency = currency
+          @intervals = intervals
+          @description = description
+          @is_active = is_active
+          @features_json = features_json
+        end
+
+        def to_hash
+          hash = {
+            name: @name,
+            description: @description,
+            amount: @amount,
+            currency: @currency,
+            intervals: @intervals,
+            is_active: @is_active
+          }
+          hash[:features_json] = @features_json unless @features_json.nil?
+          hash
+        end
+      end
+    end
+  end
+end

data/lib/tinker/model/dto/create_subscription_request_dto.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Tinker
+  module Model
+    module Dto
+      class CreateSubscriptionRequestDto
+        def initialize(plan_id:, gateway:, customer:, payment_method_id: nil, billing_period: nil, country: nil)
+          @plan_id = plan_id
+          @gateway = gateway
+          @customer = customer
+          @payment_method_id = payment_method_id
+          @billing_period = billing_period
+          @country = country
+        end
+
+        def to_hash
+          payload = {
+            plan_id: @plan_id,
+            gateway: @gateway,
+            customer: @customer.to_hash
+          }
+          payload[:payment_method_id] = @payment_method_id if @payment_method_id
+          payload[:billing_period] = @billing_period if @billing_period
+          payload[:country] = @country if @country
+          payload
+        end
+      end
+    end
+  end
+end

data/lib/tinker/model/dto/initiate_payment_request_dto.rb

@@ -5,10 +5,12 @@ module Tinker
     module Dto
       class InitiatePaymentRequestDto
         attr_reader :amount, :currency, :gateway, :merchant_reference, :return_url,
-                    :customer_phone, :customer_email, :transaction_desc, :metadata
+                    :customer_phone, :customer_email, :transaction_desc, :metadata, :payment_method,
+                    :customer_name, :country
 
         def initialize(amount:, currency:, gateway:, merchant_reference:, return_url:,
-                       customer_phone: nil, customer_email: nil, transaction_desc: nil, metadata: nil)
+                       customer_phone: nil, customer_email: nil, transaction_desc: nil, metadata: nil,
+                       payment_method: nil, customer_name: nil, country: nil)
           @amount = amount
           @currency = currency
           @gateway = gateway
@@ -18,6 +20,9 @@ module Tinker
           @customer_email = customer_email
           @transaction_desc = transaction_desc
           @metadata = metadata
+          @payment_method = payment_method
+          @customer_name = customer_name
+          @country = country
         end
 
         def to_hash
@@ -33,8 +38,11 @@ module Tinker
 
           payload[:customerPhone] = @customer_phone if @customer_phone
           payload[:customerEmail] = @customer_email if @customer_email
+          payload[:customerName] = @customer_name if @customer_name
+          payload[:country] = @country if @country
           payload[:transactionDesc] = @transaction_desc if @transaction_desc
           payload[:metadata] = @metadata if @metadata
+          payload[:paymentMethod] = @payment_method if @payment_method
 
           payload
         end

data/lib/tinker/model/dto/initiation_data_dto.rb

@@ -4,24 +4,23 @@ module Tinker
   module Model
     module Dto
       class InitiationDataDto
-        attr_reader :payment_reference, :status, :authorization_url
+        attr_reader :payment_reference, :status, :authorization_url, :client_secret, :publishable_key
 
         def initialize(data)
-          @payment_reference = data['payment_reference']
-          status_value = data['status'] || 'pending'
-          @status = begin
-            Tinker::Enum::PaymentStatus.const_get(status_value.upcase)
-          rescue NameError
-            Tinker::Enum::PaymentStatus::PENDING
-          end
-          @authorization_url = data['authorization_url']
+          @payment_reference = data['paymentReference'] || data['payment_reference']
+          @status = Tinker::Enum::PaymentStatus.parse(data['status'])
+          @authorization_url = data['authorizationUrl'] || data['authorization_url']
+          @client_secret = data['clientSecret'] || data['client_secret']
+          @publishable_key = data['publishableKey'] || data['publishable_key']
         end
 
         def to_hash
           {
-            payment_reference: @payment_reference,
+            paymentReference: @payment_reference,
             status: @status,
-            authorization_url: @authorization_url
+            authorizationUrl: @authorization_url,
+            clientSecret: @client_secret,
+            publishableKey: @publishable_key
           }
         end
       end