fakturoid 0.5.0 → 1.0.0

data/lib/fakturoid/api.rb

@@ -1,19 +1,94 @@
 # frozen_string_literal: true
 
-require "fakturoid/api/arguments"
-require "fakturoid/api/http_methods"
+require_relative "api/base"
+
+# Sorted alphabetically
+require_relative "api/account"
+require_relative "api/bank_account"
+require_relative "api/event"
+require_relative "api/expense"
+require_relative "api/expense_payment"
+require_relative "api/generator"
+require_relative "api/inbox_file"
+require_relative "api/inventory_item"
+require_relative "api/inventory_move"
+require_relative "api/invoice"
+require_relative "api/invoice_message"
+require_relative "api/invoice_payment"
+require_relative "api/number_format"
+require_relative "api/recurring_generator"
+require_relative "api/subject"
+require_relative "api/todo"
+require_relative "api/user"
 
 module Fakturoid
-  class Api
-    extend Arguments
-    extend HttpMethods
+  module Api
+    def account
+      @account ||= Account.new(self)
+    end
+
+    def bank_accounts
+      @bank_accounts ||= BankAccount.new(self)
+    end
+
+    def events
+      @events ||= Event.new(self)
+    end
+
+    def expenses
+      @expenses ||= Expense.new(self)
+    end
+
+    def expense_payments
+      @expense_payments ||= ExpensePayment.new(self)
+    end
+
+    def generators
+      @generators ||= Generator.new(self)
+    end
+
+    def inbox_files
+      @inbox_files ||= InboxFile.new(self)
+    end
+
+    def inventory_items
+      @inventory_items ||= InventoryItem.new(self)
+    end
+
+    def inventory_moves
+      @inventory_moves ||= InventoryMove.new(self)
+    end
+
+    def invoices
+      @invoices ||= Invoice.new(self)
+    end
+
+    def invoice_messages
+      @invoice_messages ||= InvoiceMessage.new(self)
+    end
+
+    def invoice_payments
+      @invoice_payments ||= InvoicePayment.new(self)
+    end
+
+    def number_formats
+      @number_formats ||= NumberFormat.new(self)
+    end
+
+    def recurring_generators
+      @recurring_generators ||= RecurringGenerator.new(self)
+    end
+
+    def subjects
+      @subjects ||= Subject.new(self)
+    end
 
-    def self.configure(&block)
-      @config ||= Fakturoid::Config.new(&block)
+    def todos
+      @todos ||= Todo.new(self)
     end
 
-    def self.config
-      @config
+    def users
+      @users ||= User.new(self)
     end
   end
 end

data/lib/fakturoid/client.rb

@@ -1,14 +1,48 @@
 # frozen_string_literal: true
 
-require "fakturoid/client/account"
-require "fakturoid/client/bank_account"
-require "fakturoid/client/number_format"
-require "fakturoid/client/user"
-require "fakturoid/client/subject"
-require "fakturoid/client/invoice"
-require "fakturoid/client/inventory_items"
-require "fakturoid/client/inventory_moves"
-require "fakturoid/client/expense"
-require "fakturoid/client/generator"
-require "fakturoid/client/event"
-require "fakturoid/client/todo"
+module Fakturoid
+  class Client
+    extend Forwardable
+    include Api
+
+    attr_reader :config
+
+    # Authorization methods
+    def_delegators :@oauth, :authorization_uri, :authorize, :revoke_access, :perform_request
+
+    def self.configure(&block)
+      @config ||= Fakturoid::Config.new(&block) # rubocop:disable  Naming/MemoizedInstanceVariableName
+    end
+
+    def self.config
+      @config
+    end
+
+    def initialize(config = {})
+      raise ConfigurationError, "Configuration is missing" if self.class.config.nil?
+
+      @config = self.class.config.duplicate(config)
+      @oauth  = Oauth.new(self)
+    end
+
+    def account=(account)
+      config.account = account
+    end
+
+    def credentials
+      config.credentials
+    end
+
+    def credentials=(values)
+      config.credentials = values
+    end
+
+    def credentials_updated_callback(&block)
+      config.credentials_updated_callback = block
+    end
+
+    def call_credentials_updated_callback
+      config.credentials_updated_callback&.call(config.credentials)
+    end
+  end
+end

data/lib/fakturoid/config.rb

@@ -2,39 +2,96 @@
 
 module Fakturoid
   class Config
-    attr_accessor :email, :api_key, :account
+    attr_accessor :email, :account, :client_id, :client_secret, :oauth_flow, :redirect_uri, :credentials_updated_callback
     attr_writer :user_agent
 
-    ENDPOINT = "https://app.fakturoid.cz/api/v2"
+    SUPPORTED_FLOWS = %w[authorization_code client_credentials].freeze
+    API_ENDPOINT = "https://app.fakturoid.cz/api/v3"
+    # API_ENDPOINT = "http://app.fakturoid.localhost/api/v3" # For development purposes
+    OAUTH_ENDPOINT = "#{API_ENDPOINT}/oauth".freeze
 
-    def initialize(&_block)
+    def initialize
       yield self
+
+      validate_configuration
+    end
+
+    def credentials
+      @credentials ||= Oauth::Credentials.new
+    end
+
+    def credentials=(values)
+      @credentials = values.is_a?(Hash) ? Oauth::Credentials.new(values) : values
     end
 
     def user_agent
-      if !defined?(@user_agent) || @user_agent.nil? || @user_agent.empty?
+      if Utils.empty?(@user_agent)
         "Fakturoid ruby gem (#{email})"
       else
         @user_agent
       end
     end
 
-    def endpoint
-      "#{ENDPOINT}/accounts/#{account}"
+    def api_endpoint
+      raise ConfigurationError, "Account slug is required" if Utils.empty?(account)
+
+      "#{API_ENDPOINT}/accounts/#{account}"
+    end
+
+    def api_endpoint_without_account
+      API_ENDPOINT
+    end
+
+    def oauth_endpoint
+      OAUTH_ENDPOINT
     end
 
-    def endpoint_without_account
-      ENDPOINT
+    def authorization_uri(state: nil)
+      params = {
+        client_id: client_id,
+        redirect_uri: redirect_uri,
+        response_type: "code"
+      }
+      params[:state] = state unless Utils.empty?(state)
+
+      connection = Faraday::Connection.new(oauth_endpoint)
+      connection.build_url(nil, params)
     end
 
-    def faraday_v1?
-      major_faraday_version == "1"
+    def access_token_auth_header
+      "#{credentials.token_type} #{credentials.access_token}"
+    end
+
+    def authorization_code_flow?
+      oauth_flow == "authorization_code"
+    end
+
+    def client_credentials_flow?
+      oauth_flow == "client_credentials"
+    end
+
+    # We can create multiple instances of the client, make sure we isolate the config for each
+    # as it contains credentials which must not be shared.
+    def duplicate(new_config)
+      self.class.new do |config|
+        config.email         = email
+        config.account       = new_config[:account] || account
+        config.user_agent    = user_agent
+        config.client_id     = client_id
+        config.client_secret = client_secret
+        config.oauth_flow    = oauth_flow # 'client_credentials', 'authorization_code'
+        # only authorization_code
+        config.redirect_uri  = redirect_uri
+      end
     end
 
   private
 
-    def major_faraday_version
-      @major_faraday_version ||= Faraday::VERSION.split(".").first
+    def validate_configuration
+      raise ConfigurationError, "Missing or unsupported OAuth flow, supported flows are - `authorization_code`, `client_credentials`" unless SUPPORTED_FLOWS.include?(oauth_flow)
+      raise ConfigurationError, "`email` or `user` agent is required" if Utils.empty?(email) && Utils.empty?(user_agent)
+      raise ConfigurationError, "Client credentials are required" if Utils.empty?(client_id) || Utils.empty?(client_secret)
+      raise ConfigurationError, "`redirect_uri` is required for Authorization Code Flow" if authorization_code_flow? && Utils.empty?(redirect_uri)
     end
   end
 end

data/lib/fakturoid/oauth/access_token_service.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Fakturoid
+  class Oauth
+    class AccessTokenService
+      attr_reader :oauth, :client
+
+      def initialize(oauth)
+        @oauth  = oauth
+        @client = oauth.client
+      end
+
+      def perform_request(method, path, params)
+        check_access_token
+        fetch_access_token if client.config.credentials.access_token_expired?
+
+        retried = false
+
+        begin
+          Request::Api.new(method, path, client).call(params)
+        rescue AuthenticationError
+          raise if retried
+          retried = true
+          fetch_access_token
+
+          retry
+        end
+      end
+
+    private
+
+      def check_access_token
+        raise ArgumentError, "OAuth access was not authorized by user" unless oauth.authorized?
+        return unless Utils.empty?(client.config.credentials.access_token)
+
+        fetch_access_token
+      end
+
+      def fetch_access_token
+        oauth.fetch_access_token.tap do
+          client.call_credentials_updated_callback
+        end
+      end
+    end
+  end
+end

data/lib/fakturoid/oauth/credentials.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Fakturoid
+  class Oauth
+    class Credentials
+      EXPIRY_BUFFER_IN_SECONDS = 10
+      MAX_EXPIRY_IN_SECONDS    = 2 * 3600 # 2 hours
+
+      attr_accessor :access_token, :refresh_token, :token_type
+      attr_reader :expires_at
+
+      def initialize(values = {})
+        update(values)
+      end
+
+      def update(values)
+        values = values.transform_keys(&:to_sym)
+
+        self.access_token  = values[:access_token]
+        self.refresh_token = values[:refresh_token] unless Utils.empty?(values[:refresh_token])
+        self.expires_at    = values[:expires_at] || values[:expires_in]
+        self.token_type  ||= values[:token_type]
+      end
+
+      def expires_at=(value)
+        @expires_at = parse_expires_at(value)
+      end
+
+      def expires_in=(value)
+        self.expires_at = value
+      end
+
+      def access_token_expired?
+        Time.now > (expires_at - EXPIRY_BUFFER_IN_SECONDS)
+      end
+
+      def as_json
+        {
+          access_token: access_token,
+          refresh_token: refresh_token,
+          expires_at: expires_at.to_datetime, # `DateTime` serializes into is8601, `Time` doesn't, so it can be saved as JSON safely.
+          token_type: token_type
+        }
+      end
+
+    private
+
+      def parse_expires_at(value)
+        case value
+          when DateTime
+            value.to_time
+          when String
+            Time.parse(value)
+          when Integer # `value` in seconds
+            raise ArgumentError, "`expires_at` cannot be unix timestamp (was #{value.inspect})" if value > MAX_EXPIRY_IN_SECONDS
+            Time.now + value
+          else
+            value
+        end
+      end
+    end
+  end
+end

data/lib/fakturoid/oauth/flow/authorization_code.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Fakturoid
+  class Oauth
+    module Flow
+      class AuthorizationCode
+        include Base
+
+        GRANT_TYPE = "authorization_code"
+
+        def authorization_uri(state: nil)
+          client.config.authorization_uri(state: state)
+        end
+
+        def authorize(code:)
+          payload = {
+            grant_type: GRANT_TYPE,
+            redirect_uri: client.config.redirect_uri,
+            code: code
+          }
+
+          response = perform_request(HTTP_POST, "token.json", payload: payload)
+          client.config.credentials.update(response.body)
+          client.call_credentials_updated_callback
+          response
+        end
+
+        def fetch_access_token
+          payload = {
+            grant_type: "refresh_token",
+            refresh_token: client.config.credentials.refresh_token
+          }
+
+          response = perform_request(HTTP_POST, "token.json", payload: payload)
+          client.config.credentials.update(response.body)
+          response
+        end
+
+        def revoke_access
+          payload = {
+            token: client.config.credentials.refresh_token
+          }
+
+          perform_request(HTTP_POST, "revoke.json", payload: payload)
+        end
+
+        def authorized?
+          !Utils.empty?(client.config.credentials.refresh_token)
+        end
+      end
+    end
+  end
+end

data/lib/fakturoid/oauth/flow/base.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Fakturoid
+  class Oauth
+    module Flow
+      module Base
+        attr_reader :client
+
+        def initialize(client)
+          @client = client
+        end
+
+        def authorization_uri(state: nil)
+          raise NotImplementedError, "Authorization path is not supported"
+        end
+
+        def authorize(code:)
+          raise NotImplementedError, "Authorize is not supported"
+        end
+
+        def fetch_access_token
+          raise NotImplementedError, "Fetch access token is not supported"
+        end
+
+        def revoke_access
+          raise NotImplementedError, "Revoke access is not supported"
+        end
+
+        def authorized?
+          raise NotImplementedError, "Authorized is not supported"
+        end
+
+      protected
+
+        def perform_request(method, path, params)
+          raw_response = Request::Oauth.new(method, path, client).call(params)
+          TokenResponse.new(raw_response)
+        end
+      end
+    end
+  end
+end

data/lib/fakturoid/oauth/flow/client_credentials.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Fakturoid
+  class Oauth
+    module Flow
+      class ClientCredentials
+        include Base
+
+        GRANT_TYPE = "client_credentials"
+
+        def fetch_access_token
+          payload = {
+            grant_type: GRANT_TYPE
+          }
+
+          response = perform_request(HTTP_POST, "token.json", payload: payload)
+          client.config.credentials.update(response.body)
+          response
+        end
+
+        def authorized?
+          true
+        end
+      end
+    end
+  end
+end

data/lib/fakturoid/oauth/flow.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "flow/base"
+require_relative "flow/authorization_code"
+require_relative "flow/client_credentials"

data/lib/fakturoid/oauth/request/api.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Fakturoid
+  class Oauth
+    module Request
+      class Api
+        include Base
+      end
+    end
+  end
+end

data/lib/fakturoid/oauth/request/base.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Fakturoid
+  class Oauth
+    module Request
+      module Base
+        attr_reader :method, :path, :client
+
+        HTTP_METHODS = [:get, :post, :patch, :delete].freeze
+        REQUEST_TIMEOUT = 10
+
+        def initialize(method, path, client)
+          @method = method
+          @path   = path
+          @client = client
+        end
+
+        def call(params = {})
+          raise ArgumentError, "Unknown http method: #{method}" unless HTTP_METHODS.include?(method.to_sym)
+
+          request_params = params[:request_params] || {}
+
+          http_connection = connection(params)
+
+          http_connection.send(method) do |req|
+            req.url path, request_params
+            req.body = MultiJson.dump(params[:payload]) if params.key?(:payload)
+          end
+        end
+
+      protected
+
+        def default_options(options = {})
+          {
+            headers: {
+              content_type: "application/json",
+              accept: "application/json",
+              user_agent: client.config.user_agent
+            },
+            url: options[:url] || endpoint,
+            request: {
+              timeout: REQUEST_TIMEOUT
+            }
+          }
+        end
+
+        def endpoint
+          client.config.api_endpoint
+        end
+
+        def connection(options = {})
+          Faraday.new default_options(options) do |conn|
+            conn.headers[:authorization] = client.config.access_token_auth_header
+            conn.adapter Faraday.default_adapter
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fakturoid/oauth/request/oauth.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Fakturoid
+  class Oauth
+    module Request
+      class Oauth
+        include Base
+
+      protected
+
+        def connection(options = {})
+          Faraday.new default_options(options) do |conn|
+            conn.set_basic_auth(client.config.client_id, client.config.client_secret)
+            conn.adapter Faraday.default_adapter
+          end
+        end
+
+        def endpoint
+          client.config.oauth_endpoint
+        end
+      end
+    end
+  end
+end

data/lib/fakturoid/oauth/request.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "request/base"
+require_relative "request/api"
+require_relative "request/oauth"

data/lib/fakturoid/oauth/token_response.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Fakturoid
+  class Oauth
+    class TokenResponse
+      attr_reader :client, :response, :body
+
+      def initialize(response)
+        @response = response
+        @body     = MultiJson.load(response.env.body) unless Utils.empty?(response.env.body)
+
+        handle_response
+      end
+
+      def status_code
+        response.env["status"]
+      end
+
+      def refresh_token
+        body["refresh_token"]
+      end
+
+      def access_token
+        body["access_token"]
+      end
+
+      def expires_in
+        body["expires_in"]
+      end
+
+      def token_type
+        body["token_type"]
+      end
+
+      def inspect
+        "#<#{self.class.name}:#{object_id} @body=\"#{body}\" @status_code=\"#{status_code}\">"
+      end
+
+    private
+
+      def handle_response
+        case status_code
+          when 400 then raise error(OauthError, "OAuth request failed")
+          when 401 then raise error(AuthenticationError, "OAuth authentication failed")
+          else
+            raise error(ServerError, "Server error") if status_code >= 500
+            raise error(ClientError, "Client error") if status_code >= 400
+        end
+      end
+
+      def error(klass, message = nil)
+        klass.new message, status_code, body
+      end
+    end
+  end
+end