tamara 0.1.0

data/lib/tamara/api/payment_types.rb

@@ -0,0 +1,23 @@
+module Tamara
+  class PaymentTypes < ApplicationService
+    include Tamara::JsonSchemas::PaymentTypes
+
+    def self.list(country: "SA", order_value: 1, opts: {})
+      new(country: country, order_value: order_value, opts: opts).call
+    end
+
+    def call_api
+      ::Faraday.get(url, api_params, headers)
+    end
+
+    private
+
+    def url
+      "#{Tamara.checkout_uri}/payment-types"
+    end
+
+    def api_params
+      @api_params ||= { country: @params[:country], order_value: @params[:order_value] }
+    end
+  end
+end

data/lib/tamara/api/payments/capture.rb

@@ -0,0 +1,40 @@
+module Tamara
+  module Payments
+    class Capture < ApplicationService
+      include Tamara::JsonSchemas::Payments::Capture
+
+      def self.call(order_id:, total_amount:, shipping_info:, items: [], shipping_amount: nil, tax_amount: nil, discount_amount: nil, opts: {})
+        new(order_id: order_id,
+            total_amount: total_amount,
+            shipping_info: shipping_info,
+            items: items,
+            shipping_amount: shipping_amount,
+            tax_amount: tax_amount,
+            discount_amount: discount_amount,
+            opts: opts).call
+      end
+
+      def call_api
+        ::Faraday.post(url, api_params.to_json, headers)
+      end
+
+      private
+
+      def url
+        "#{Tamara.payments_uri}/capture"
+      end
+
+      def api_params
+        @api_params ||= {
+          order_id: @params[:order_id],
+          total_amount: @params[:total_amount],
+          shipping_info: @params[:shipping_info],
+          items: @params[:items],
+          shipping_amount: @params[:shipping_amount],
+          tax_amount: @params[:tax_amount],
+          discount_amount: @params[:discount_amount]
+        }
+      end
+    end
+  end
+end

data/lib/tamara/api/payments.rb

@@ -0,0 +1,16 @@
+module Tamara
+  module Payments
+    def self.capture(order_id:, total_amount:, shipping_info:, items: [], shipping_amount: nil, tax_amount: nil, discount_amount: nil, opts: {})
+      Tamara::Payments::Capture.call(
+        order_id: order_id,
+        total_amount: total_amount,
+        shipping_info: shipping_info,
+        shipping_amount: shipping_amount,
+        tax_amount: tax_amount,
+        discount_amount: discount_amount,
+        items: items,
+        opts: opts
+      )
+    end
+  end
+end

data/lib/tamara/api/request.rb

@@ -0,0 +1,49 @@
+module Tamara
+  module Request
+    def headers
+      @headers = {
+        "Content-Type": "application/json",
+        Authorization: "Bearer #{api_token}"
+      }
+    end
+
+    def api_token
+      @opts[:api_token] || Tamara.api_token || Tamara.configuration.api_token
+    end
+
+    def parsed_response
+      @parsed_response ||= begin
+        JSON.parse(@response.body)
+      rescue StandardError
+        {}
+      end
+    end
+
+    def error_message
+      @error_message = parsed_response[:message]
+    end
+
+    def response_status
+      @response_status = @response.status
+    end
+
+    def response_body
+      @response_body = @response.body
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    def handle_response_error
+      case response_status
+      when 400
+        raise InvalidRequestError.new(error_message, parsed_response.dig(:errors, 0, :error_code), http_status: response_status, http_body: response_body)
+      when 401
+        raise AuthenticationError.new("Invalid API key", http_status: response_status, http_body: response_body)
+      when 404
+        raise APIError.new("Resource not found", http_status: response_status, http_body: response_body)
+      when (400..599)
+        raise APIError.new(error_message, http_status: response_status, http_body: response_body)
+      end
+    end
+    # rubocop:enable Metrics/AbcSize
+  end
+end

data/lib/tamara/api/signature.rb

@@ -0,0 +1,25 @@
+require "jwt"
+
+module Tamara
+  class Signature < ApplicationService
+    def self.verify(token, opts: {})
+      new(token: token, opts: opts).call
+    end
+
+    def call
+      begin
+        decoded = ::JWT.decode(@params[:token], notification_token, true, { algorithm: "HS256" })
+      rescue StandardError => e
+        return failure(e.message)
+      end
+
+      success(decoded)
+    end
+
+    private
+
+    def notification_token
+      @opts[:notification_token] || Tamara.notification_token || Tamara.configuration.notification_token
+    end
+  end
+end

data/lib/tamara/api/webhooks.rb

@@ -0,0 +1,28 @@
+module Tamara
+  class Webhooks < ApplicationService
+    include Tamara::JsonSchemas::Webhook
+
+    def self.register(type:, events:, url:, headers: {}, opts: {})
+      new(type: type, events: events, url: url, headers: headers, opts: opts).call
+    end
+
+    def call_api
+      ::Faraday.post(url, api_params.to_json, headers)
+    end
+
+    def url
+      Tamara.webhooks_uri
+    end
+
+    private
+
+    def api_params
+      @api_params ||= {
+        type: @params[:type],
+        events: @params[:events],
+        url: @params[:url],
+        headers: @params[:headers]
+      }
+    end
+  end
+end

data/lib/tamara/configuration.rb

@@ -0,0 +1,5 @@
+module Tamara
+  class Configuration
+    attr_accessor :api_token, :notification_token, :public_key, :checkout_optional_keys
+  end
+end

data/lib/tamara/errors.rb

@@ -0,0 +1,67 @@
+module Tamara
+  # TamaraError is the base error from which all other more specific Tamara
+  # errors derive.
+  class TamaraError < StandardError
+    attr_reader :message, :error, :http_body, :http_headers, :http_status, :json_body
+
+    # Initializes a TamaraError.
+    def initialize(message = nil, http_status: nil, http_body: nil)
+      @message = message || http_body
+      @http_status = http_status
+      @http_body = http_body
+      begin
+        @json_body = JSON.parse(http_body)
+      rescue StandardError
+        @json_body = nil
+      end
+    end
+
+    def to_s
+      status_string = @http_status.nil? ? "" : "(Status #{@http_status}) "
+      "#{status_string}#{@message}"
+    end
+  end
+
+  # ConfigurationMissingError is raised when a configuration is missing
+  class ConfigurationMissingError < StandardError; end
+
+  # AuthenticationError is raised when invalid credentials are used to connect
+  # to Tamara's servers.
+  class AuthenticationError < TamaraError
+  end
+
+  # APIConnectionError is raised in the event that the SDK can't connect to
+  # Tamara's servers. That can be for a variety of different reasons from a
+  # downed network to a bad TLS certificate.
+  class APIConnectionError < TamaraError
+  end
+
+  # APIError is a generic error that may be raised in cases where none of the
+  # other named errors cover the problem. It could also be raised in the case
+  # that a new error has been introduced in the API, but this version of the
+  # Ruby SDK doesn't know how to handle it.
+  class APIError < TamaraError
+  end
+
+  # InvalidRequestError is raised when a request is initiated with invalid
+  # parameters.
+  class InvalidRequestError < TamaraError
+    attr_accessor :param
+
+    def initialize(message, param, http_status: nil, http_body: nil)
+      super(message, http_status: http_status, http_body: http_body)
+      @param = param
+    end
+  end
+
+  # SignatureVerificationError is raised when the signature verification for a
+  # webhook fails
+  class SignatureVerificationError < TamaraError
+    attr_accessor :sig_header
+
+    def initialize(message, sig_header, http_body: nil)
+      super(message, http_body: http_body)
+      @sig_header = sig_header
+    end
+  end
+end

data/lib/tamara/hmac.rb

@@ -0,0 +1,20 @@
+module Tamara
+  module Hmac
+    FILTERED_TRANSACTION_KEYS = %w[amount_cents created_at currency error_occured has_parent_transaction id
+                                   integration_id is_3d_secure is_auth is_capture is_refunded is_standalone_payment
+                                   is_voided order.id owner pending
+                                   source_data.pansource_data.sub_type source_data.type success].freeze
+
+    class << self
+      def valid_signature?(tamara_response)
+        digest = ::OpenSSL::Digest.new("sha512")
+
+        concatenated_str = FILTERED_TRANSACTION_KEYS.map do |element|
+          tamara_response.dig("obj", *element.split("."))
+        end.join
+        secure_hash = ::OpenSSL::HMAC.hexdigest(digest, Tamara.hmac_key, concatenated_str)
+        secure_hash == tamara_response["hmac"]
+      end
+    end
+  end
+end

data/lib/tamara/json_schemas/address.rb

@@ -0,0 +1,23 @@
+module Tamara
+  module JsonSchemas
+    module Address
+      def self.schema(allows_null: false)
+        {
+          "$schema": "http://json-schema.org/draft-06/schema",
+          type: ["object", (allows_null ? "null" : nil)].compact,
+          properties: {
+            city: Types::String.schema,
+            country_code: Types::Enum.schema(values: COUNTRY_CODES, default: "SA"),
+            first_name: Types::String.schema,
+            last_name: Types::String.schema,
+            line1: Types::String.schema,
+            line2: Types::String.schema(allows_null: true),
+            phone_number: Types::String.schema(allows_null: true),
+            region: Types::String.schema(allows_null: true)
+          },
+          required: %w[city country_code first_name last_name line1]
+        }
+      end
+    end
+  end
+end

data/lib/tamara/json_schemas/amount.rb

@@ -0,0 +1,19 @@
+module Tamara
+  module JsonSchemas
+    module Amount
+      CURRENCIES = %w[SAR AED BHD KWD OMR].freeze
+
+      def self.schema(allows_null: false)
+        {
+          "$schema": "http://json-schema.org/draft-06/schema",
+          type: ["object", (allows_null ? "null" : nil)].compact,
+          properties: {
+            amount: Types::Float.schema(min: 0.1),
+            currency: Types::Enum.schema(values: CURRENCIES, default: "SAR")
+          },
+          required: %w[amount currency]
+        }
+      end
+    end
+  end
+end

data/lib/tamara/json_schemas/checkout_optional_keys.rb

@@ -0,0 +1,11 @@
+module Tamara
+  module JsonSchemas
+    module CheckoutOptionalKeys
+      def checkout_optional_keys
+        @params ||= {}
+        checkout_optional_keys = @params.dig(:opts, :checkout_optional_keys) || Tamara.configuration.checkout_optional_keys
+        checkout_optional_keys.is_a?(Hash) ? checkout_optional_keys : {}
+      end
+    end
+  end
+end

data/lib/tamara/json_schemas/consumer.rb

@@ -0,0 +1,21 @@
+module Tamara
+  module JsonSchemas
+    module Consumer
+      def self.schema(allows_null: false)
+        {
+          "$schema": "http://json-schema.org/draft-06/schema",
+          type: ["object", (allows_null ? "null" : nil)].compact,
+          properties: {
+            first_name: Types::String.schema,
+            last_name: Types::String.schema,
+            email: {
+              pattern: URI::MailTo::EMAIL_REGEXP
+            },
+            phone_number: Types::String.schema
+          },
+          required: %w[first_name last_name email phone_number]
+        }
+      end
+    end
+  end
+end

data/lib/tamara/json_schemas/discount.rb

@@ -0,0 +1,17 @@
+module Tamara
+  module JsonSchemas
+    module Discount
+      def self.schema(allows_null: false)
+        {
+          "$schema": "http://json-schema.org/draft-06/schema",
+          type: ["object", (allows_null ? "null" : nil)].compact,
+          properties: {
+            name: Types::String.schema,
+            amount: Amount.schema
+          },
+          required: %w[name amount]
+        }
+      end
+    end
+  end
+end

data/lib/tamara/json_schemas/item.rb

@@ -0,0 +1,41 @@
+module Tamara
+  module JsonSchemas
+    module Item
+      extend CheckoutOptionalKeys
+
+      REQUIRED_KEYS = %w[name quantity reference_id type sku total_amount].freeze
+
+      # rubocop:disable Metrics/AbcSize
+      def self.schema(params = nil)
+        @params = params
+        {
+          "$schema": "http://json-schema.org/draft-06/schema",
+          type: "object",
+          properties: {
+            name: Types::String.schema(allows_null: filtered_keys.exclude?("name")),
+            quantity: Types::Integer.schema(min: 1, allows_null: filtered_keys.exclude?("quantity")),
+            reference_id: Types::String.schema(allows_null: filtered_keys.exclude?("reference_id")),
+            type: Types::String.schema(allows_null: filtered_keys.exclude?("type")),
+            sku: Types::String.schema(max_length: 128, allows_null: filtered_keys.exclude?("sku")),
+            item_url: Types::Url.schema(allows_null: filtered_keys.exclude?("item_url")),
+            image_url: Types::Url.schema(allows_null: filtered_keys.exclude?("image_url")),
+            unit_price: Amount.schema(allows_null: filtered_keys.exclude?("unit_price")),
+            tax_amount: Amount.schema(allows_null: filtered_keys.exclude?("tax_amount")),
+            discount_amount: Amount.schema(allows_null: filtered_keys.exclude?("discount_amount")),
+            total_amount: Amount.schema(allows_null: filtered_keys.exclude?("total_amount"))
+          },
+          required: filtered_keys
+        }
+      end
+      # rubocop:enable Metrics/AbcSize
+
+      def self.filtered_keys
+        @filtered_keys ||= begin
+          optional_keys = (checkout_optional_keys[:items] || []).map(&:to_s)
+
+          REQUIRED_KEYS - optional_keys
+        end
+      end
+    end
+  end
+end

data/lib/tamara/json_schemas/merchant_url.rb

@@ -0,0 +1,19 @@
+module Tamara
+  module JsonSchemas
+    module MerchantUrl
+      def self.schema(allows_null: false)
+        {
+          "$schema": "http://json-schema.org/draft-06/schema",
+          type: ["object", (allows_null ? "null" : nil)].compact,
+          properties: {
+            cancel: Types::Url.schema,
+            failure: Types::Url.schema,
+            success: Types::Url.schema,
+            notification: Types::Url.schema(allows_null: true)
+          },
+          required: %w[cancel failure success]
+        }
+      end
+    end
+  end
+end

data/lib/tamara/json_schemas/orders/cancel.rb

@@ -0,0 +1,30 @@
+module Tamara
+  module JsonSchemas
+    module Orders
+      module Cancel
+        include Validator
+
+        private
+
+        def schema
+          {
+            "$schema": "http://json-schema.org/draft-06/schema",
+            type: "object",
+            properties: {
+              order_id: Types::Uuid.schema,
+              total_amount: Amount.schema,
+              shipping_amount: Amount.schema(allows_null: true),
+              tax_amount: Amount.schema(allows_null: true),
+              discount_amount: Amount.schema(allows_null: true),
+              items: {
+                type: "array",
+                items: Item.schema
+              }
+            },
+            required: %w[order_id total_amount]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/tamara/json_schemas/orders/create.rb

@@ -0,0 +1,61 @@
+module Tamara
+  module JsonSchemas
+    module Orders
+      module Create
+        include CheckoutOptionalKeys
+        include Validator
+
+        PAYMENT_TYPES = %w[PAY_BY_INSTALMENTS PAY_NOW].freeze
+        LOCALES       = %w[ar_SA en_US].freeze
+
+        REQUIRED_KEYS = %w[order_reference_id country_code description total_amount shipping_amount tax_amount
+                           consumer items merchant_url shipping_address payment_type instalments risk_assessment].freeze
+
+        private
+
+        # rubocop:disable Metrics/AbcSize
+        def schema
+          {
+            "$schema": "http://json-schema.org/draft-06/schema",
+            type: "object",
+            properties: {
+              order_reference_id: Types::String.schema(allows_null: filtered_keys.exclude?("order_reference_id")),
+              country_code: Types::Enum.schema(values: COUNTRY_CODES, default: "SA"),
+              description: Types::String.schema(max_length: 256, allows_null: filtered_keys.exclude?("description")),
+              total_amount: Amount.schema(allows_null: filtered_keys.exclude?("total_amount")),
+              shipping_amount: Amount.schema(allows_null: filtered_keys.exclude?("shipping_amount")),
+              tax_amount: Amount.schema(allows_null: filtered_keys.exclude?("tax_amount")),
+              consumer: Consumer.schema(allows_null: filtered_keys.exclude?("consumer")),
+              items: {
+                type: "array",
+                minItems: 1,
+                items: Item.schema(@params)
+              },
+              merchant_url: MerchantUrl.schema(allows_null: filtered_keys.exclude?("merchant_url")),
+              shipping_address: Address.schema(allows_null: filtered_keys.exclude?("shipping_address")),
+              payment_type: Types::Enum.schema(values: PAYMENT_TYPES, default: "PAY_BY_INSTALMENTS"),
+              instalments: Types::Integer.schema(min: 1, default: 3),
+              order_number: Types::String.schema(allows_null: filtered_keys.exclude?("order_number")),
+              discount: Discount.schema(allows_null: true),
+              billing_address: Address.schema(allows_null: true),
+              platform: Types::String.schema(allows_null: true),
+              is_mobile: Types::Boolean.schema(default: false),
+              locale: Types::Enum.schema(values: LOCALES, default: "ar_SA"),
+              expires_in_minutes: Types::Integer.schema(min: 5, max: 1440, default: 30),
+              risk_assessment: RiskAssessment.schema(allows_null: filtered_keys.exclude?("risk_assessment"), params: @params)
+            },
+            required: filtered_keys
+          }
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        def filtered_keys
+          @filtered_keys ||= begin
+            optional_keys = checkout_optional_keys.select { |_k, v| v.empty? }.keys.map(&:to_s)
+            REQUIRED_KEYS - optional_keys
+          end
+        end
+      end
+    end
+  end
+end

data/lib/tamara/json_schemas/payment_options/check.rb

@@ -0,0 +1,25 @@
+module Tamara
+  module JsonSchemas
+    module PaymentOptions
+      module Check
+        include Validator
+
+        private
+
+        def schema
+          {
+            "$schema": "http://json-schema.org/draft-06/schema",
+            type: "object",
+            properties: {
+              country: Types::Enum.schema(values: COUNTRY_CODES, default: "SA"),
+              phone_number: Types::String.schema,
+              order_value: Amount.schema,
+              is_vip: Types::Boolean.schema(default: false)
+            },
+            required: %w[country phone_number order_value]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/tamara/json_schemas/payment_types.rb

@@ -0,0 +1,21 @@
+module Tamara
+  module JsonSchemas
+    module PaymentTypes
+      include Validator
+
+      private
+
+      def schema
+        {
+          "$schema": "http://json-schema.org/draft-06/schema",
+          type: "object",
+          properties: {
+            country: Types::Enum.schema(values: COUNTRY_CODES, default: "SA"),
+            order_value: Types::Float.schema(min: 0.1)
+          },
+          required: %w[country order_value]
+        }
+      end
+    end
+  end
+end

data/lib/tamara/json_schemas/payments/capture.rb

@@ -0,0 +1,38 @@
+module Tamara
+  module JsonSchemas
+    module Payments
+      module Capture
+        include Validator
+
+        private
+
+        def schema
+          {
+            "$schema": "http://json-schema.org/draft-06/schema",
+            type: "object",
+            properties: {
+              order_id: Types::Uuid.schema,
+              total_amount: Amount.schema,
+              shipping_info: {
+                type: "object",
+                properties: {
+                  shipped_at: Types::String.schema,
+                  shipping_company: Types::String.schema
+                },
+                required: %w[shipped_at shipping_company]
+              },
+              items: {
+                type: "array",
+                items: Item.schema
+              },
+              shipping_amount: Amount.schema(allows_null: true),
+              tax_amount: Amount.schema(allows_null: true),
+              discount_amount: Amount.schema(allows_null: true)
+            },
+            required: %w[order_id total_amount shipping_info]
+          }
+        end
+      end
+    end
+  end
+end