simpal 0.1.0

data/README.md

@@ -0,0 +1,61 @@
+# Simpal
+
+A simple, lightweight wrapper around PayPal's REST API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'simpal'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install simpal
+
+## Usage
+
+First, create a client ID and secret from the [Applications](https://developer.paypal.com/developer/applications) page
+of your PayPal account dashboard.
+
+Then, create a client which uses these credentials:
+
+```ruby
+Simpal.client = Simpal::Client.new(
+  client_id: 'CLIENT_ID',
+  client_secret: 'CLIENT_SECRET',
+  sandbox: true
+)
+```
+
+The value of **Simpal.client** is to make requests, unless the **client** attribute is specified on a per-request basis.
+The **sandbox** attribute defaults to **false** if omitted.
+
+Once the client has been setup, it's easy to retrieve an order:
+
+```ruby
+Simpal::Order.retrieve('ORDER_ID')
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/nialtoservices/simpal. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/nialtoservices/simpal/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [Apache 2.0 License](https://opensource.org/licenses/Apache-2.0).
+
+## Code of Conduct
+
+Everyone interacting in the Simpal project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/simpal/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'simpal'
+require 'pry'
+
+Pry.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/simpal.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday_middleware'
+require 'json'
+require 'singleton'
+require 'time'
+
+require_relative 'simpal/constants'
+require_relative 'simpal/middleware/authorization'
+require_relative 'simpal/middleware/headers'
+require_relative 'simpal/client_error'
+require_relative 'simpal/client'
+require_relative 'simpal/pay_pal_object'
+require_relative 'simpal/api/orders'
+require_relative 'simpal/api/payments/authorizations'
+require_relative 'simpal/api/payments/captures'
+require_relative 'simpal/api/payments/refunds'
+require_relative 'simpal/order'
+require_relative 'simpal/payment/authorization'
+require_relative 'simpal/payment/capture'
+require_relative 'simpal/payment/refund'
+
+# A simple, lightweight wrapper around PayPal's REST API.
+#
+module Simpal
+  class << self
+    # @return [Simpal::Client] The default client to use when performing API requests.
+    #
+    attr_accessor :client
+
+    # Returns the API client to use for a set of request parameters.
+    #
+    # @param  client [Simpal::Client, nil] The preferred client, or `nil`.
+    # @return        [Simpal::Client]      The client to make the request with.
+    # @raise         [Simpal::ClientError] When an acceptable `Simpal::Client` can't be found.
+    #
+    def client_for(client)
+      client ||= self.client
+      return client if client.is_a?(Simpal::Client)
+
+      raise ClientError, 'API client is missing. Did you forget to set `Simpal.client`?'
+    end
+  end
+end

data/lib/simpal/api/orders.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Simpal
+  module API
+    # @see https://developer.paypal.com/docs/api/orders/v2/
+    #
+    module Orders
+      # Create an order.
+      #
+      # @param  params  [Hash]           The parameters for the create request.
+      # @param  headers [Hash]           The custom headers to add to the request.
+      # @param  client  [Simpal::Client] The API client to make the request with.
+      # @return         [Hash]           A Hash representing the order.
+      #
+      def self.create(params = {}, headers: {}, client: nil)
+        client = Simpal.client_for(client)
+        response = client.connection.post('/v2/checkout/orders', params, headers)
+        response.body
+      end
+
+      # Update an order.
+      #
+      # @param  id      [String]         The ID of an existing order.
+      # @param  params  [Array<Hash>]    The collection of patches to apply to the order.
+      # @param  headers [Hash]           The custom headers to add to the request.
+      # @param  client  [Simpal::Client] The API client to make the request with.
+      # @return         [Hash]           An empty hash.
+      #
+      def self.update(id, params = [], headers: {}, client: nil)
+        client = Simpal.client_for(client)
+        response = client.connection.patch("/v2/checkout/orders/#{id}", params, headers)
+        response.body
+      end
+
+      # Retrieve an order.
+      #
+      # @param  id      [String]         The ID of an existing order.
+      # @param  headers [Hash]           The custom headers to add to the request.
+      # @param  client  [Simpal::Client] The API client to make the request with.
+      # @return         [Hash]           A Hash representing the order.
+      #
+      def self.retrieve(id, headers: {}, client: nil)
+        client = Simpal.client_for(client)
+        response = client.connection.get("/v2/checkout/orders/#{id}", headers)
+        response.body
+      end
+
+      # Authorize the payment for an order.
+      #
+      # @param  id      [String]         The ID of an existing order.
+      # @param  params  [Hash]           The parameters for the authorize request.
+      # @param  headers [Hash]           The custom headers to add to the request.
+      # @param  client  [Simpal::Client] The API client to make the request with.
+      # @return         [Hash]           A Hash representing the order.
+      #
+      def self.authorize(id, params = {}, headers: {}, client: nil)
+        client = Simpal.client_for(client)
+        response = client.connection.post("/v2/checkout/orders/#{id}/authorize", params, headers)
+        response.body
+      end
+
+      # Capture the payment for an order.
+      #
+      # @param  id      [String]         The ID of an existing order.
+      # @param  params  [Hash]           The parameters for the capture request.
+      # @param  headers [Hash]           The custom headers to add to the request.
+      # @param  client  [Simpal::Client] The API client to make the request with.
+      # @return         [Hash]           A Hash representing the order.
+      #
+      def self.capture(id, params = {}, headers: {}, client: nil)
+        client = Simpal.client_for(client)
+        response = client.connection.post("/v2/checkout/orders/#{id}/capture", params, headers)
+        response.body
+      end
+    end
+  end
+end

data/lib/simpal/api/payments/authorizations.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Simpal
+  module API
+    # @see https://developer.paypal.com/docs/api/payments/v2/
+    #
+    module Payments
+      # @see https://developer.paypal.com/docs/api/payments/v2/#authorizations
+      #
+      module Authorizations
+        # Retrieve an authorized payment.
+        #
+        # @param  id      [String]         The ID of an authorized payment.
+        # @param  headers [Hash]           The custom headers to add to the request.
+        # @param  client  [Simpal::Client] The API client to make the request with.
+        # @return         [Hash]           A Hash representing the authorized payment.
+        #
+        def self.retrieve(id, headers: {}, client: nil)
+          client = Simpal.client_for(client)
+          response = client.connection.get("/v2/payments/authorizations/#{id}", headers)
+          response.body
+        end
+
+        # Capture an authorized payment.
+        #
+        # @param  id      [String]         The ID of an authorized payment.
+        # @param  params  [Hash]           The parameters for the capture request.
+        # @param  headers [Hash]           The custom headers to add to the request.
+        # @param  client  [Simpal::Client] The API client to make the request with.
+        # @return         [Hash]           A Hash representing the captured payment.
+        #
+        def self.capture(id, params = {}, headers: {}, client: nil)
+          client = Simpal.client_for(client)
+          response = client.connection.post("/v2/payments/authorizations/#{id}/capture", params, headers)
+          response.body
+        end
+
+        # Reauthorize an authorized payment.
+        #
+        # @param  id      [String]         The ID of an authorized payment.
+        # @param  params  [Hash]           The parameters for the reauthorize request.
+        # @param  headers [Hash]           The custom headers to add to the request.
+        # @param  client  [Simpal::Client] The API client to make the request with.
+        # @return         [Hash]           A Hash representing the reauthorized payment.
+        #
+        def self.reauthorize(id, params = {}, headers: {}, client: nil)
+          client = Simpal.client_for(client)
+          response = client.connection.post("/v2/payments/authorizations/#{id}/reauthorize", params, headers)
+          response.body
+        end
+
+        # Void an authorized payment.
+        #
+        # @param  id      [String]         The ID of an authorized payment.
+        # @param  headers [Hash]           The custom headers to add to the request.
+        # @param  client  [Simpal::Client] The API client to make the request with.
+        # @return         [Hash]           An empty hash.
+        #
+        def self.void(id, headers: {}, client: nil)
+          client = Simpal.client_for(client)
+          response = client.connection.post("/v2/payments/authorizations/#{id}/void", nil, headers)
+          response.body
+        end
+      end
+    end
+  end
+end

data/lib/simpal/api/payments/captures.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Simpal
+  module API
+    # @see https://developer.paypal.com/docs/api/payments/v2/
+    #
+    module Payments
+      # @see https://developer.paypal.com/docs/api/payments/v2/#captures
+      #
+      module Captures
+        # Retrieve a captured payment.
+        #
+        # @param  id      [String]         The ID of a captured payment.
+        # @param  headers [Hash]           The custom headers to add to the request.
+        # @param  client  [Simpal::Client] The API client to make the request with.
+        # @return         [Hash]           A Hash representing the captured payment.
+        #
+        def self.retrieve(id, headers: {}, client: nil)
+          client = Simpal.client_for(client)
+          response = client.connection.get("/v2/payments/captures/#{id}", headers)
+          response.body
+        end
+
+        # Refund a captured payment.
+        #
+        # @param  id      [String]         The ID of a captured payment.
+        # @param  params  [Hash]           The parameters for the refund request.
+        # @param  headers [Hash]           The custom headers to add to the request.
+        # @param  client  [Simpal::Client] The API client to make the request with.
+        # @return         [Hash]           A Hash representing the captured payment.
+        #
+        def self.refund(id, params = {}, headers: {}, client: nil)
+          client = Simpal.client_for(client)
+          response = client.connection.post("/v2/payments/captures/#{id}/refund", params, headers)
+          response.body
+        end
+      end
+    end
+  end
+end

data/lib/simpal/api/payments/refunds.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Simpal
+  module API
+    # @see https://developer.paypal.com/docs/api/payments/v2/
+    #
+    module Payments
+      # @see https://developer.paypal.com/docs/api/payments/v2/#refunds
+      #
+      module Refunds
+        # Retrieve a refunded payment.
+        #
+        # @param  id      [String]         The ID of a refunded payment.
+        # @param  headers [Hash]           The custom headers to add to the request.
+        # @param  client  [Simpal::Client] The API client to make the request with.
+        # @return         [Hash]           A Hash representing the refunded payment.
+        #
+        def self.retrieve(id, headers: {}, client: nil)
+          client = Simpal.client_for(client)
+          response = client.connection.get("/v2/payments/refunds/#{id}", headers)
+          response.body
+        end
+      end
+    end
+  end
+end

data/lib/simpal/client.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Simpal
+  # Provides an API client for performing requests under an account within a particular environment.
+  #
+  # PayPal API credentials can be obtained from the following URL:
+  #   => https://developer.paypal.com/developer/applications
+  #
+  class Client
+    # @return [String] The 'Client ID' from your PayPal account dashboard.
+    #
+    attr_reader :client_id
+
+    # @return [String] The 'Client Secret' from your PayPal account dashboard.
+    #
+    attr_reader :client_secret
+
+    # @return [Boolean] `true` when using the sandbox API, `false` when using the production API.
+    #
+    attr_reader :sandbox
+
+    # Create a new API client.
+    #
+    # @parameter client_id     [String]  The 'Client ID' from your PayPal account dashboard.
+    # @parameter client_secret [String]  The 'Client Secret' from your PayPal account dashboard.
+    # @parameter sandbox       [Boolean] `true` when using the sandbox API, `false` when using the live API.
+    #
+    def initialize(client_id:, client_secret:, sandbox: false)
+      @client_id = client_id
+      @client_secret = client_secret
+      @sandbox = sandbox
+    end
+
+    # @return [String] The URL for the PayPal API service.
+    #
+    def service_url
+      if sandbox
+        'https://api-m.sandbox.paypal.com'
+      else
+        'https://api-m.paypal.com'
+      end
+    end
+
+    # @return [Hash] The default headers, which should be merged into every API request.
+    #
+    def headers
+      { 'User-Agent' => "Simpal/#{Simpal::VERSION}" }
+    end
+
+    # @return [Faraday::Connection] The connection to use when executing an API request.
+    #
+    def connection
+      @connection ||= Faraday.new(service_url, headers: headers) do |connection|
+        connection.use Faraday::Response::RaiseError
+        connection.use Simpal::Middleware::Headers
+        connection.use FaradayMiddleware::EncodeJson
+        connection.use FaradayMiddleware::ParseJson
+        connection.use Simpal::Middleware::Authorization, self
+        connection.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/simpal/client_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Simpal
+  # Indicates an error related to a `Simpal::Client`.
+  #
+  class ClientError < StandardError; end
+end

data/lib/simpal/constants.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Simpal
+  VERSION = '0.1.0'
+end

data/lib/simpal/middleware/authorization.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Simpal
+  module Middleware
+    # Requests an OAuth2 access token for a `Simpal::Client`, adding the resulting access token into each request.
+    #
+    class Authorization < Faraday::Middleware
+      # @return [Simpal::Client] The client which we're handling the 'Authorization' header for.
+      #
+      attr_reader :client
+
+      # @return [String] The access token to include in each request.
+      #
+      attr_reader :access_token
+
+      # @return [Time] The time at which the access token expires.
+      #
+      attr_reader :access_token_expires_at
+
+      def initialize(app, client)
+        super(app)
+        @client = client
+      end
+
+      def call(request_env)
+        retryable = true
+        refresh_access_token
+
+        begin
+          request_env[:request_headers].merge!('Authorization' => "Bearer #{access_token}")
+          super(request_env)
+        rescue Faraday::UnauthorizedError
+          raise unless retryable
+
+          retryable = false
+          refresh_access_token!
+          retry
+        end
+      end
+
+      private
+
+      def connection
+        @connection ||= Faraday.new(client.service_url, headers: client.headers) do |connection|
+          connection.use Faraday::Request::UrlEncoded
+          connection.use Faraday::Response::RaiseError
+          connection.use FaradayMiddleware::ParseJson
+          connection.basic_auth(client.client_id, client.client_secret)
+        end
+      end
+
+      def refresh_access_token!
+        response = connection.post('/v1/oauth2/token', grant_type: :client_credentials)
+        @access_token = response.body['access_token']
+        @access_token_expires_at = Time.httpdate(response.headers['date']) + response.body['expires_in']
+      end
+
+      def refresh_access_token
+        return if access_token && access_token_expires_at && (access_token_expires_at - Time.now) >= 1
+
+        refresh_access_token!
+      end
+    end
+  end
+end