tamara 0.1.0

data/README.md

@@ -0,0 +1,290 @@
+# Tamara
+
+Ruby gem for [Tamara](https://tamara.co/en-SA)
+
+For reference on the internals & specifics of Tamara, please head to their [official documentation](https://docs.tamara.co/docs/)
+
+# Table of Contents
+1. [Installation](#installation)
+1. [Configuration](#configuration)
+1. [APIs](#apis)
+    1. [List Available Payment Types](#list-available-payment-types)
+    1. [Check Payment Options Availability](#check-payment-options-availability)
+    1. [Orders](#online-checkout)
+        1. [Create](#create)
+        1. [Authorize](#authorize)
+        1. [Cancel](#cancel)
+        1. [Order Details](#order-details)
+            1. [Get Order Details by Tamara's order_id](#get-order-details-by-tamaras-order_id)
+            1. [Get Order Details by Merchant's order_reference_id](#get-order-details-by-merchants-order_reference_id)
+      1. [Payments](#payments)
+        1. [Capture](#capture)
+      1. [Webhooks](#webhooks)
+        1. [Register Webhook](#register-webhook)
+  1. [Errors](#errors)
+  1. [Contributing](#contributing)
+  1. [License](#license)
+
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add tamara
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install tamara
+
+Next, you need to run the generator:
+
+    $ rails generate tamara:install
+
+## Configuration
+
+Configure the gem with your configuration
+
+```ruby
+Tamara.configure do |config|
+  config.api_token = "api_token"
+  config.notification_token = "notification_token"
+  config.public_key = "public_key"
+  config.checkout_optional_keys = {}
+end
+```
+
+For `api_token`, you can set its value in 3 ways
+- Global across whole application (through initializer and configuration)
+  ```ruby
+  Tamara.configure do |config|
+    config.api_token = "api_token"
+  end
+  ```
+
+- Per method or block (through the application variables). All consecutive requests will use that token until it is set to a different value
+  ```ruby
+  Tamara.api_token = "api_token"
+  ```
+
+- Per request (through opts parameter)
+  ```ruby
+  Tamara::PaymentTypes.list(opts: { api_token: "api_token" })
+  ```
+
+## APIs
+
+Any API call will return an object with following methods: 
+
+```ruby
+result = Tamara.doSomething
+result.success?
+result.failure?
+result.payload
+result.error
+```
+
+### [List Available Payment Types](https://docs.tamara.co/reference/paymenttypes)
+
+```ruby
+Tamara::PaymentTypes.list(country: "SA", order_value: 1)
+```
+
+### [Check Payment Options Availability](https://docs.tamara.co/reference/checkpaymentoptionsavailability)
+
+```ruby
+Tamara::PaymentOptions.check(country: "SA", phone_number: "544337766", order_value: { amount: 100, currency: "SAR" })
+```
+
+### Online Checkout:
+
+#### [Create](https://docs.tamara.co/reference/createcheckoutsession)
+
+```ruby
+Tamara::Orders.create(
+  order_reference_id: "abd12331-a123-1234-4567-fbde34ae",
+  country_code: "SA",
+  description: "Enter order description here",
+  total_amount: {
+    amount: 300,
+    currency: "SAR"
+  },
+  shipping_amount: {
+    amount: 10,
+    currency: "SAR"
+  },
+  tax_amount: {
+    amount: 0,
+    currency: "SAR"
+  },
+  consumer: {
+    email: "customer@email.com",
+    first_name: "Mona",
+    last_name: "Lisa",
+    phone_number: "566027755"
+  },
+  items: [
+    {
+      name: "Lego City 8601",
+      type: "Digital",
+      reference_id: "123",
+      sku: "SA-12436",
+      quantity: 1,
+      unit_price: {
+        amount: 490,
+        currency: "SAR"
+      },
+      total_amount: {
+        amount: 100,
+        currency: "SAR"
+      }
+    }
+  ],
+  merchant_url: {
+    cancel: "http://example.com/#/cancel",
+    failure: "http://example.com/#/fail",
+    success: "http://example.com/#/success",
+    notification: "https://example-notification.com/payments/tamaranotifications"
+  },
+  shipping_address: {
+    city: "Riyadh",
+    country_code: "SA",
+    first_name: "Mona",
+    last_name: "Lisa",
+    line1: "3764 Al Urubah Rd",
+    line2: "string",
+    phone_number: "532298658",
+    region: "As Sulimaniyah"
+  }
+)
+```
+
+:exclamation::exclamation::exclamation: For creating an online checkout session, some information might be optional. You can configure these through `checkout_optional_keys` in your initializer.
+
+The below example will make `description` key optional and `sku, type` optional for `items` array.
+
+```ruby
+Tamara.configure do |config|
+  config.checkout_optional_keys = { description: [], items: [:sku, :type] }
+end
+```
+
+:warning: This will not make `items` key optional. To do so, you need to pass an empty array `[]` to the key
+
+```ruby
+Tamara.configure do |config|
+  config.checkout_optional_keys = { description: [], items: [] }
+end
+```
+
+#### [Authorize](https://docs.tamara.co/reference/authoriseorder)
+
+```ruby
+Tamara::Orders.authorize(order_id: "ff776045-513b-4cd7-8b4f-e60673daad84")
+```
+
+#### [Cancel](https://docs.tamara.co/reference/cancelorder)
+
+```ruby
+Tamara::Orders.cancel(
+  order_id: "abd12331-a123-1234-4567-fbde34ae",
+  total_amount: {
+    amount: 300,
+    currency: "SAR"
+  }
+)
+```
+
+### Order Details
+#### [Get Order Details by Tamara's order_id](https://docs.tamara.co/reference/getorderdetails)
+
+```ruby
+Tamara::Orders.get_by_tamara_order_id(order_id: "ff776045-513b-4cd7-8b4f-e60673daad84")
+```
+
+#### [Get Order Details by Merchant's order_reference_id](https://docs.tamara.co/reference/getorderdetailsbyrefid)
+
+```ruby
+Tamara::Orders.get_by_merchant_order_reference_id(order_id: "ff776045-513b-4cd7-8b4f-e60673daad84")
+```
+
+## Payments
+#### [Capture](https://docs.tamara.co/reference/captureorder)
+
+```ruby
+Tamara::Payments.capture(
+  order_id: "ff776045-513b-4cd7-8b4f-e60673daad84",
+  total_amount: {
+    amount: 300,
+    currency: "SAR"
+  },
+  shipping_info: {
+    shipped_at: "2020-03-31T19:19:52.677Z",
+    shipping_company: "DHL",
+    tracking_number: "100",
+    tracking_url: "https://shipping.com/tracking?id=123456"
+  },
+  items: [
+    {
+      name: "Lego City 8601",
+      type: "Digital",
+      reference_id: "123",
+      sku: "SA-12436",
+      quantity: 1,
+      discount_amount: {
+        amount: 100,
+        currency: "SAR"
+      },
+      tax_amount: {
+        amount: 10,
+        currency: "SAR"
+      },
+      unit_price: {
+        amount: 490,
+        currency: "SAR"
+      },
+      total_amount: {
+        amount: 100,
+        currency: "SAR"
+      }
+    }
+  ]
+)
+```
+
+## Webhooks
+### [Register Webhook](https://docs.tamara.co/reference/registerwebhookurl)
+
+```ruby
+Tamara::Webhooks.register(
+  type: "order",
+  events: [
+    "order_approved",
+    "order_authorised",
+    "order_canceled",
+    "order_updated",
+    "order_captured",
+    "order_refunded"
+  ],
+  url: "https://www.enteryoursitehere.com/webhooks",
+  headers: {
+    authorization: "123344-1231-abcd-adfe-123456"
+  }
+)
+```
+
+## Errors:
+Errors could be one of the following:
+
+```ruby
+Tamara::AuthenticationError
+Tamara::InvalidRequestError (With `param` attribute)
+Tamara::APIError
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,19 @@
+require "bundler/gem_tasks"
+
+require "rake"
+begin
+  require "bundler/setup"
+  Bundler::GemHelper.install_tasks
+rescue LoadError
+  puts "although not required, bundler is recommended for running the tests"
+end
+
+task default: :spec
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new do |task|
+  task.requires << "rubocop-performance"
+  task.requires << "rubocop-rspec"
+end

data/lib/generators/tamara/install_generator.rb

@@ -0,0 +1,15 @@
+require "rails/generators"
+
+module Tamara
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Tamara initializers file."
+
+      def copy_initializer
+        copy_file "tamara.rb", "config/initializers/tamara.rb"
+      end
+    end
+  end
+end

data/lib/generators/tamara/templates/tamara.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+Tamara.configure do |config|
+  # config.api_token = ""
+  # config.notification_token = ""
+  # config.public_key = ""
+  config.checkout_optional_keys = {}
+end

data/lib/tamara/api/api_token.rb

@@ -0,0 +1,14 @@
+module Tamara
+  class ApiToken < ApplicationService
+    def self.verify(opts: {})
+      new(opts: opts).verify
+    end
+
+    def verify
+      result = Tamara::PaymentTypes.list(opts: @opts)
+      return failure(result.error) if result.failure?
+
+      success("API Token is valid")
+    end
+  end
+end

data/lib/tamara/api/application_service.rb

@@ -0,0 +1,48 @@
+module Tamara
+  class ApplicationService
+    include Tamara::Request
+
+    Response = Struct.new(:success?, :payload, :error) do
+      def failure?
+        !success?
+      end
+    end
+
+    def initialize(**params)
+      @params = params
+      @opts   = params[:opts] || {}
+    end
+
+    def call
+      validate_params!
+      @response = call_api
+      handle_response_error
+
+      success(parsed_response)
+    rescue StandardError => e
+      failure(e)
+    end
+
+    private
+
+    def validate_params!
+      raise NotImplementedError, "Subclasses must implement validate_params!"
+    end
+
+    def call_api
+      raise NotImplementedError, "Subclasses must implement call_api"
+    end
+
+    def url
+      raise NotImplementedError, "Subclasses must implement url"
+    end
+
+    def success(payload = nil)
+      Response.new(true, payload)
+    end
+
+    def failure(exception)
+      Response.new(false, nil, exception)
+    end
+  end
+end

data/lib/tamara/api/orders/authorize.rb

@@ -0,0 +1,26 @@
+module Tamara
+  module Orders
+    class Authorize < ApplicationService
+      include Tamara::JsonSchemas::Validator
+      include Tamara::JsonSchemas::Types::Uuid
+
+      def self.call(order_id:, opts: {})
+        new(order_id: order_id, opts: opts).call
+      end
+
+      def call_api
+        ::Faraday.post(url, {}.to_json, headers)
+      end
+
+      private
+
+      def url
+        "#{Tamara.orders_uri}/#{@params[:order_id]}/authorise"
+      end
+
+      def api_params
+        @api_params ||= @params[:order_id]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+module Tamara
+  module Orders
+    class Cancel < ApplicationService
+      include Tamara::JsonSchemas::Orders::Cancel
+
+      def self.call(order_id:, total_amount:, items: [], shipping_amount: nil, tax_amount: nil, discount_amount: nil, opts: {})
+        new(order_id: order_id,
+            total_amount: total_amount,
+            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.orders_uri}/#{@params[:order_id]}/cancel"
+      end
+
+      def api_params
+        @api_params ||= {
+          order_id: @params[:order_id],
+          total_amount: @params[:total_amount],
+          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/orders/create.rb

@@ -0,0 +1,71 @@
+module Tamara
+  module Orders
+    class Create < ApplicationService
+      include Tamara::JsonSchemas::Orders::Create
+
+      # rubocop:disable Layout/LineLength
+      def self.call(order_reference_id:, country_code:, description:, total_amount:, shipping_amount:, tax_amount:, consumer:, items:, merchant_url:, shipping_address:, payment_type: "PAY_BY_INSTALMENTS", installments: 3, order_number: nil, discount: nil, billing_address: nil, platform: "", is_mobile: false, locale: "ar_SA", risk_assessment: nil, additional_data: nil, expires_in_minutes: 30, opts: {})
+        new(order_reference_id: order_reference_id,
+            country_code: country_code,
+            description: description,
+            total_amount: total_amount,
+            shipping_amount: shipping_amount,
+            tax_amount: tax_amount,
+            consumer: consumer,
+            items: items,
+            merchant_url: merchant_url,
+            shipping_address: shipping_address,
+            payment_type: payment_type,
+            installments: installments,
+            order_number: order_number,
+            discount: discount,
+            billing_address: billing_address,
+            platform: platform,
+            is_mobile: is_mobile,
+            locale: locale,
+            risk_assessment: risk_assessment,
+            additional_data: additional_data,
+            expires_in_minutes: expires_in_minutes,
+            opts: opts).call
+      end
+      # rubocop:enable Layout/LineLength
+
+      def call_api
+        ::Faraday.post(url, api_params.to_json, headers)
+      end
+
+      def url
+        Tamara.checkout_uri
+      end
+
+      private
+
+      # rubocop:disable Metrics/AbcSize
+      def api_params
+        @api_params ||= {
+          order_reference_id: @params[:order_reference_id],
+          country_code: @params[:country_code],
+          description: @params[:description],
+          total_amount: @params[:total_amount],
+          shipping_amount: @params[:shipping_amount],
+          tax_amount: @params[:tax_amount],
+          consumer: @params[:consumer],
+          items: @params[:items],
+          merchant_url: @params[:merchant_url],
+          shipping_address: @params[:shipping_address],
+          payment_type: @params[:payment_type],
+          instalments: @params[:installments],
+          order_number: @params[:order_number],
+          discount: @params[:discount],
+          billing_address: @params[:billing_address],
+          platform: @params[:platform],
+          is_mobile: @params[:is_mobile],
+          locale: @params[:locale],
+          risk_assessment: @params[:risk_assessment],
+          additional_data: @params[:additional_data]
+        }
+      end
+      # rubocop:enable Metrics/AbcSize
+    end
+  end
+end

data/lib/tamara/api/orders/details/merchant_order.rb

@@ -0,0 +1,28 @@
+module Tamara
+  module Orders
+    module Details
+      class MerchantOrder < ApplicationService
+        include Tamara::JsonSchemas::Validator
+        include Tamara::JsonSchemas::Types::String
+
+        def self.call(order_reference_id:, opts: {})
+          new(order_reference_id: order_reference_id, opts: opts).call
+        end
+
+        def call_api
+          ::Faraday.get(url, {}, headers)
+        end
+
+        private
+
+        def url
+          "#{Tamara.base_uri}/merchants/orders/reference-id/#{@params[:order_reference_id]}"
+        end
+
+        def api_params
+          @api_params ||= @params[:order_reference_id]
+        end
+      end
+    end
+  end
+end

data/lib/tamara/api/orders/details/tamara_order.rb

@@ -0,0 +1,28 @@
+module Tamara
+  module Orders
+    module Details
+      class TamaraOrder < ApplicationService
+        include Tamara::JsonSchemas::Validator
+        include Tamara::JsonSchemas::Types::Uuid
+
+        def self.call(order_id:, opts: {})
+          new(order_id: order_id, opts: opts).call
+        end
+
+        def call_api
+          ::Faraday.get(url, {}, headers)
+        end
+
+        private
+
+        def url
+          "#{Tamara.orders_uri}/#{@params[:order_id]}"
+        end
+
+        def api_params
+          @api_params ||= @params[:order_id]
+        end
+      end
+    end
+  end
+end

data/lib/tamara/api/orders.rb

@@ -0,0 +1,56 @@
+module Tamara
+  module Orders
+    def self.get_by_tamara_order_id(order_id:, opts: {})
+      Tamara::Orders::Details::TamaraOrder.call(order_id: order_id, opts: opts)
+    end
+
+    def self.get_by_merchant_order_reference_id(order_reference_id:, opts: {})
+      Tamara::Orders::Details::MerchantOrder.call(order_reference_id: order_reference_id, opts: opts)
+    end
+
+    def self.authorize(order_id:, opts: {})
+      Tamara::Orders::Authorize.call(order_id: order_id, opts: opts)
+    end
+
+    def self.cancel(order_id:, total_amount:, items: [], shipping_amount: nil, tax_amount: nil, discount_amount: nil, opts: {})
+      Tamara::Orders::Cancel.call(
+        order_id: order_id,
+        total_amount: total_amount,
+        shipping_amount: shipping_amount,
+        tax_amount: tax_amount,
+        discount_amount: discount_amount,
+        items: items,
+        opts: opts
+      )
+    end
+
+    # rubocop:disable Layout/LineLength
+    def self.create(order_reference_id:, country_code:, description:, total_amount:, shipping_amount:, tax_amount:, consumer:, items:, merchant_url:, shipping_address:, payment_type: "PAY_BY_INSTALMENTS", installments: 3, order_number: nil, discount: nil, billing_address: nil, platform: "", is_mobile: false, locale: "ar_SA", risk_assessment: nil, additional_data: nil, expires_in_minutes: 30, opts: {})
+      Tamara::Orders::Create.call(
+        order_reference_id: order_reference_id,
+        country_code: country_code,
+        description: description,
+        total_amount: total_amount,
+        shipping_amount: shipping_amount,
+        tax_amount: tax_amount,
+        consumer: consumer,
+        items: items,
+        merchant_url: merchant_url,
+        shipping_address: shipping_address,
+        payment_type: payment_type,
+        installments: installments,
+        order_number: order_number,
+        discount: discount,
+        billing_address: billing_address,
+        platform: platform,
+        is_mobile: is_mobile,
+        locale: locale,
+        risk_assessment: risk_assessment,
+        additional_data: additional_data,
+        expires_in_minutes: expires_in_minutes,
+        opts: opts
+      )
+    end
+    # rubocop:enable Layout/LineLength
+  end
+end

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

@@ -0,0 +1,34 @@
+module Tamara
+  module PaymentOptions
+    class Check < ApplicationService
+      include Tamara::JsonSchemas::PaymentOptions::Check
+
+      def self.call(country:, phone_number:, order_value:, is_vip: false, opts: {})
+        new(country: country,
+            phone_number: phone_number,
+            order_value: order_value,
+            is_vip: is_vip,
+            opts: opts).call
+      end
+
+      def call_api
+        ::Faraday.post(url, api_params.to_json, headers)
+      end
+
+      private
+
+      def url
+        "#{Tamara.checkout_uri}/payment-options-pre-check"
+      end
+
+      def api_params
+        @api_params ||= {
+          country: @params[:country],
+          phone_number: @params[:phone_number],
+          order_value: @params[:order_value],
+          is_vip: @params[:is_vip]
+        }
+      end
+    end
+  end
+end

data/lib/tamara/api/payment_options.rb

@@ -0,0 +1,13 @@
+module Tamara
+  module PaymentOptions
+    def self.check(country:, phone_number:, order_value:, is_vip: false, opts: {})
+      Tamara::PaymentOptions::Check.call(
+        country: country,
+        phone_number: phone_number,
+        order_value: order_value,
+        is_vip: is_vip,
+        opts: opts
+      )
+    end
+  end
+end