business_central 0.9.3

data/lib/business_central/api_methods.rb

@@ -0,0 +1,220 @@
+##
+# Provides an interface between the object methods and the API
+#
+module BusinessCentral
+  module ApiMethods
+
+    # The method_missing method is used to determine if a called method exists
+    # in the defined constant for each local object - SUPPORTED_METHODS. This
+    # ensures that only supported operations can be called.
+    #
+    # @param method_name [String]
+    # @param args [Array]]
+    # @param block [Block]
+    #
+    def method_missing(method_name, *args, &block)
+      if supported_method?(method_name.to_sym)
+        self.send(method_name.to_sym, args)
+      else
+        "#{method_name} is not supported"
+      end
+    end
+
+    # Determines if the GET operation is for all remote objects, a single
+    # object, or a single object with optional parameters being supplied
+    #
+    # When no parameters are supplied, the GET will be for all remote objects
+    # eg
+    #   .get()
+    #
+    # When one parameter is supplied, the GET will be for the single object
+    # eg
+    #   .get("1234")
+    #
+    # When more than one parameter is supplied, the GET will be for the single
+    # object, and then for the supplied optional parameters
+    #
+    # An example of the options is 
+    #   .get("1234", "$extended=customerFinancialDetails")
+    #
+    # @param args [Array]]
+    #
+    def get(*args)
+      case args.length
+      when 0
+        find_collection
+      when 1
+        find_by_id(args[0]).first
+      else
+        find_by_id_with_options(*args).first
+      end
+    end
+
+    # Gets a child object, or array of child objects
+    #
+    # When only the parent_id is supplied, the GET will return all child
+    # objects of that parent
+    # eg
+    #   get_child(1234)
+    #
+    # when both paremeters are present, the GET will return the single child
+    # object
+    # eg
+    #   get_child(1234, 4321)
+    #
+    # @param parent_id [String]
+    # @param child_id [String]
+    #
+    def get_child(parent_id, child_id = nil)
+      url = build_url(parent_id, child_id)
+
+      response = @client.get(url)
+      handle_error(response)
+      results = process(response)
+
+      if results.is_a?(Array)
+        return results if child_id.nil? || results.length > 1
+        return results.first
+      end
+    end
+
+    # Performs a GET operation with a supplied filter string, to search for
+    # remote objects.
+    #
+    # eg
+    #   .get("'lastModifiedDate lt '2019-01-01T01:01:01+08:00'")
+    #
+    # @param args [Array]]
+    #
+    def query(*args)
+      response = @client.get("/#{api_object}?$filter=#{args[0]}")
+      handle_error(response)
+      process(response)
+    end
+
+    # Performs the POST operation on the supplied args
+    #
+    # @param args [Array]]
+    #
+    def create(*args)
+      return if args.length == 0
+      post(args[0]).first
+    end
+
+    # Performs the PATCH operation on the supplied args
+    #
+    # Expects arguments (id, etag, data)
+    #
+    # @param args [Array]]
+    #
+    def update(*args)
+      return if args.length == 0
+      patch(args[0], args[1], args[2]).first
+    end
+
+    # Performs the DELETE operation on the supplied args
+    #
+    # Expects arguments (id, etag)
+    #
+    # @param args [Array]
+    #
+    def delete(*args)
+      return if args.length == 0
+      destroy(args[0], args[1])
+    end
+
+    private
+
+    # Finds and returns an array of remote objects
+    #
+    def find_collection
+      response = @client.get("/#{api_object}")
+      handle_error(response)
+      process(response)
+    end
+
+    # Finds and returns the single object
+    #
+    # @param id [String]
+    #
+    def find_by_id(id)
+      response = @client.get("/#{api_object}(#{id})")
+      handle_error(response)
+      process(response)
+    end
+
+    # Finds and returns the single object, with additional options
+    #
+    # @param args [Array]
+    #
+    def find_by_id_with_options(*args)
+      id = args[0]
+      options = args[1]
+
+      response = @client.get("/#{api_object}(#{id})?#{options}")
+      handle_error(response)
+      process(response)
+    end
+
+    # POSTs supplied data to the API
+    #
+    # @param data [Hash]
+    #
+    def post(data)
+      response = @client.post("/#{api_object}", data)
+      handle_error(response)
+      process(response)
+    end
+
+    # Performs the PATCH operation
+    #
+    # @param id [String]
+    # @param etag [String]
+    # @param data [Hash]
+    #
+    def patch(id, etag, data)
+      response = @client.patch("/#{api_object}(#{id})", etag, data)
+      handle_error(response)
+      process(response)
+    end
+
+    # Performs the actual DELETE operation
+    #
+    # @param id [String] the remote object ID
+    # @param etag [String] the remote object etag
+    #
+    # @returns [Net::HTTPResponse.code]
+    #
+    def destroy(id, etag)
+      response = @client.delete("/#{api_object}(#{id})", etag)
+      handle_error(response)
+      response.code
+    end
+
+    # Each class definition that corresponds to an API endpoint will have
+    # a constant defined that identifies the object to call on the API.
+    #
+    def api_object
+      self.class.const_get(:API_OBJECT)
+    end
+
+    # Some API endpoints are for child objects. In those class definitions
+    # a constant is defined to identify the parent object
+    #
+    def api_object_parent
+      self.class.const_get(:API_OBJECT_PARENT)
+    end
+
+    # Not all operations are supported on all API endpoints, so each class
+    # definition has an array of supported methods defined in a constant. This
+    # function determines if the method supplied is supported, after being
+    # called by :method_missing
+    #
+    # @param method [String]
+    # @returns [Boolean]
+    #
+    def supported_method?(method_name)
+      self.class.const_get(:SUPPORTED_METHODS).include?(method_name)
+    end
+  end
+end

data/lib/business_central/balance_sheet.rb

@@ -0,0 +1,10 @@
+##
+# Provides access to the /balanceSheet API
+#
+
+module BusinessCentral
+  class BalanceSheet < BusinessCentral::Base
+    API_OBJECT = "balanceSheet"
+    SUPPORTED_METHODS = [:get]
+  end
+end

data/lib/business_central/base.rb

@@ -0,0 +1,56 @@
+##
+# Provides the mechanisms to interact with the BusinessCentral API
+#
+
+module BusinessCentral
+  class Base
+    include BusinessCentral::ApiMethods
+
+    attr_reader :client
+
+    # The +Base+ class used to provide functionality to subclasses
+    #
+    # @param client [BusinessCentral::Client]
+    #
+    def initialize(client)
+      @client = client.nil? ? BusinessCentral::Client.new() : client
+    end
+
+    # Use a BusinessCentral::Response::ResponseHandler to proces the results
+    # from the API query
+    #
+    # @param response [Net::HTTPResponse]
+    #
+    def process(response)
+      BusinessCentral::Response::ResponseHandler.
+        new(@client.dataset(response)).
+        compiled_data
+    end
+
+    # Use the BusinessCentral::URLBuilder to create the URL to query the API
+    #
+    # @param parent_id [String] the ID of the parent object
+    # @param child_id [String] any additional options
+    #
+    def build_url(parent_id, child_id = nil)
+      options = { child_path: api_object }
+
+      if !child_id.nil?
+        options[:child_id] = child_id
+      end
+
+      BusinessCentral::URLBuilder.new(api_object_parent, parent_id, options).url
+    end
+
+    private
+
+    # Check to see if the response contains an error and raise an error if
+    # required
+    #
+    # @param response [Net::HTTPResponse]
+    #
+    def handle_error(response)
+      # raise ServiceUnavailableError unless ["200", "201", "204"].include?(response.code)
+    end
+  end
+end

data/lib/business_central/cash_flow_statement.rb

@@ -0,0 +1,10 @@
+##
+# Provides access to the /cashFlowStatement API
+#
+
+module BusinessCentral
+  class CashFlowStatement < BusinessCentral::Base
+    API_OBJECT = "cashFlowStatement"
+    SUPPORTED_METHODS = [:get]
+  end
+end

data/lib/business_central/client.rb

@@ -0,0 +1,128 @@
+#.data_store.nil?.data_store.nil?#
+# An object to handle authentication with BusinessCentral and to 
+# provide the transport mechanism for interacting with the BusinessCentral API
+#
+module BusinessCentral
+  class Client
+    attr_reader :api_username, :api_password, :api_tenant, :api_company_id,
+      :api_host, :api_version, :api_path
+
+    # Creates an instance of the BusinessCentral::Client.
+    #
+    # Pass in a Hash of the various options:
+    #   api_version: The path of the API Version - eg "/v1.0"
+    #   api_path: Appended after the API Version - eg "/api/v1.0"
+    #   api_username: Used for Basic Auth
+    #   api_password: Used for Basic Auth
+    #   api_tenant: The tenant domain for your BusinessCentral installation
+    #   api_company_id: The company that will be queried
+    #
+    # @param opts [Hash] A Hash with login configuration options
+    #
+    def initialize(opts = {})
+      @api_version = opts[:api_version] ||= BusinessCentral::API_VERSION
+      @api_path = opts[:api_path] ||= BusinessCentral::API_PATH
+      @api_tenant = opts[:api_tenant] ||= ENV['BC_TENANT']
+      @api_username = opts[:api_username] ||= ENV['BC_USERNAME']
+      @api_password = opts[:api_password] ||= ENV['BC_PASSWORD']
+      @api_company_id = opts[:api_company_id] ||= ENV['BC_COMPANY_ID']
+      @api_host = opts[:api_host] ||= ENV['BC_HOST']
+    end
+
+    # Returns the URL used for interacting with the API
+    #
+    # @returns [String]
+    #
+    def base_url
+      url = "#{@api_host}#{@api_version}/#{@api_tenant}#{@api_path}"
+      unless @api_company_id.nil?
+        url += "/companies(#{@api_company_id})"
+      end
+      url
+    end
+
+    # Performs a GET operation
+    #
+    # @param url [String] The URL to perform a request on
+    # @returns Net::HttpResponse
+    #
+    def get(url)
+      request = build_request({ verb: "Get", url: url })
+      perform_request(request)
+    end
+
+    # Performs a POST operation
+    #
+    # @param url [String] The URL to perform a request on
+    # @param data [Hash] The data to POST to the URL
+    # @returns Net::HttpResponse
+    #
+    def post(url, data)
+      request = build_request({ verb: "Post", url: url, data: data })
+      perform_request(request)
+    end
+
+    # Performs a PATCH operation
+    #
+    # @param url [String] The URL to perform a request on
+    # @param etag [String] The etag of the remote object on BusinessCentral
+    # @param data [Hash] The data to PATCH the remote object with
+    # @returns Net::HttpResponse
+    #
+    def patch(url, etag, data)
+      request = build_request({ verb: "Patch", url: url, data: data, etag: etag })
+      perform_request(request)
+    end
+
+    # Performs a DELETE operation
+    #
+    # @param url [String] The URL to perform a request on
+    # @param etag [String] The etag of the remote object on BusinessCentral
+    # @returns Net::HttpResponse
+    #
+    def delete(url, etag)
+      request = build_request({ verb: "Delete", url: url, etag: etag })
+      perform_request(request)
+    end
+
+    def dataset(response)
+      json = JSON.parse(response.body)
+      if !json["value"].nil?
+        json["value"]
+      else
+        json
+      end
+    # rescue
+    #   {}
+    end
+
+    protected
+
+    # @param url [String] the URL to convert
+    # @returns URI [URI]
+    #
+    def get_uri(url)
+      URI(base_url + url)
+    end
+
+    # Build the actual Request object used to perform the operation
+    #
+    # @param opts [Hash] contains the request information
+    # @returns [Net::HTTP::Request]
+    #
+    def build_request(opts)
+      BusinessCentral::RequestBuilder.new(self, opts).request
+    end
+
+    # Performs the actual operation
+    #
+    # @param request [Net::HTTP::Request]
+    # @returns [Net::HTTP::Response]
+    #
+    def perform_request(request)
+      Net::HTTP.start(request.uri.hostname, request.uri.port, use_ssl: true) do |http|
+        http.request(request)
+      end
+    end
+  end
+end

data/lib/business_central/company.rb

@@ -0,0 +1,9 @@
+##
+# Access the /company API on BusinessCentral
+#
+module BusinessCentral
+  class Company < BusinessCentral::Base
+    API_OBJECT = "companies"
+    SUPPORTED_METHODS = [:get]
+  end
+end

data/lib/business_central/company_information.rb

@@ -0,0 +1,10 @@
+##
+# Provides access to the /companyInformation({Id}) API
+#
+
+module BusinessCentral
+  class CompanyInformation < BusinessCentral::Base
+    API_OBJECT = "companyInformation"
+    SUPPORTED_METHODS = [:get, :update]
+  end
+end

data/lib/business_central/countries_region.rb

@@ -0,0 +1,9 @@
+##
+# Provides access to the /countriesRegions API
+#
+module BusinessCentral
+  class CountriesRegion < BusinessCentral::Base
+    API_OBJECT = "countriesRegions"
+    SUPPORTED_METHODS = [:get, :create, :update, :delete]
+  end
+end

data/lib/business_central/currency.rb

@@ -0,0 +1,9 @@
+##
+# Provides access to the /currencies API
+#
+module BusinessCentral
+  class Currency < BusinessCentral::Base
+    API_OBJECT = "currencies"
+    SUPPORTED_METHODS = [:get, :create, :update, :delete]
+  end
+end

data/lib/business_central/customer.rb

@@ -0,0 +1,9 @@
+##
+# Access the /customer API on BusinessCentral
+#
+module BusinessCentral
+  class Customer < BusinessCentral::Base
+    API_OBJECT = "customers"
+    SUPPORTED_METHODS = [:get, :create, :update, :delete, :collection_filter]
+  end
+end

data/lib/business_central/customer_financial_details.rb

@@ -0,0 +1,10 @@
+##
+# Access the /customerFinancialDetails API on BusinessCentral
+#
+
+module BusinessCentral
+  class CustomerFinancialDetails < BusinessCentral::Base
+    API_OBJECT = "customerFinancialDetails"
+    SUPPORTED_METHODS = [:get]
+  end
+end

data/lib/business_central/customer_payment.rb

@@ -0,0 +1,14 @@
+##
+# Provides access to the /customerPaymentsJournal/{Id}/customerPayments API
+#
+
+module BusinessCentral
+  class CustomerPayment < BusinessCentral::Base
+    API_OBJECT_PARENT = "customerPaymentsJournal"
+    API_OBJECT = "customerPayments"
+
+    def get(customer_payments_journal_id, customer_payment_id = nil)
+      get_child(customer_payments_journal_id, customer_payment_id)
+    end
+  end
+end

data/lib/business_central/customer_payments_journal.rb

@@ -0,0 +1,10 @@
+##
+# Provides access to the /customerPaymentsJournals API
+#
+
+module BusinessCentral
+  class CustomerPaymentsJournal < BusinessCentral::Base
+    API_OBJECT = "customerPaymentsJournal"
+    SUPPORTED_METHOD = [:get, :create, :update, :delete]
+  end
+end

data/lib/business_central/customer_sales.rb

@@ -0,0 +1,10 @@
+##
+# Provides access to the /customerSales API
+#
+
+module BusinessCentral
+  class CustomerSales < BusinessCentral::Base
+    API_OBJECT = "customerSales"
+    SUPPORTED_METHODS = [:get]
+  end
+end

data/lib/business_central/dimension.rb

@@ -0,0 +1,10 @@
+##
+# Provides access to the /dimensions API
+#
+
+module BusinessCentral
+  class Dimension < BusinessCentral::Base
+    API_OBJECT = "dimensions"
+    SUPPORTED_METHODS = [:get]
+  end
+end

data/lib/business_central/dimension_line.rb

@@ -0,0 +1,14 @@
+##
+# Provides access to the /dimensions/{Id}/dimensionsLine API
+#
+
+module BusinessCentral
+  class DimensionLine < BusinessCentral::Base
+    API_OBJECT_PARENT = "dimensions"
+    API_OBJECT = "dimensionLines"
+
+    def get(dimension_id, dimension_line_id=nil)
+      get_child(dimension_id, dimension_line_id)
+    end
+  end
+end

data/lib/business_central/employee.rb

@@ -0,0 +1,10 @@
+##
+# Provides access to the /employees API
+#
+
+module BusinessCentral
+  class Employee < BusinessCentral::Base
+    API_OBJECT = "employees"
+    SUPPORTED_METHODS = [:get, :create, :update, :delete]
+  end
+end

data/lib/business_central/general_ledger_entry.rb

@@ -0,0 +1,10 @@
+##
+# Provides access to the /generalLedgeEntries API
+#
+
+module BusinessCentral
+  class GeneralLedgerEntry < BusinessCentral::Base
+    API_OBJECT = "generalLedgerEntries"
+    SUPPORTED_METHODS = [:get]
+  end
+end

data/lib/business_central/income_statement.rb

@@ -0,0 +1,10 @@
+##
+# Provides access to the /incomeStatement API
+#
+
+module BusinessCentral
+  class IncomeStatement < BusinessCentral::Base
+    API_OBJECT = "incomeStatement"
+    SUPPORTED_METHODS = [:get]
+  end
+end

data/lib/business_central/irs_1099_code.rb

@@ -0,0 +1,10 @@
+##
+# Provides access to the /irs1099Codes API
+#
+
+module BusinessCentral
+  class Irs1099Code < BusinessCentral::Base
+    API_OBJECT = "irs1099Codes"
+    SUPPORTED_METHODS = [:get, :create, :update, :delete]
+  end
+end

data/lib/business_central/item.rb

@@ -0,0 +1,10 @@
+##
+# Provides access to the /items API
+#
+
+module BusinessCentral
+  class Item < BusinessCentral::Base
+    API_OBJECT = "items"
+    SUPPORTED_METHODS = [:get, :create, :update, :delete]
+  end
+end

data/lib/business_central/item_category.rb

@@ -0,0 +1,10 @@
+##
+# Provides access to the /itemCategories API
+#
+
+module BusinessCentral
+  class ItemCategory < BusinessCentral::Base
+    API_OBJECT = "itemCategories"
+    SUPPORTED_METHODS = [:get, :create, :update, :delete]
+  end
+end

data/lib/business_central/journal.rb

@@ -0,0 +1,10 @@
+##
+# Provides access to the /journals API
+#
+
+module BusinessCentral
+  class Journal < BusinessCentral::Base
+    API_OBJECT = "journals"
+    SUPPORTED_METHODS = [:get, :create, :update, :delete]
+  end
+end

data/lib/business_central/journal_line.rb

@@ -0,0 +1,14 @@
+##
+# Provides access to the /journals/{Id}/journalLines API
+#
+
+module BusinessCentral
+  class JournalLine < BusinessCentral::Base
+    API_OBJECT_PARENT = "journals"
+    API_OBJECT = "journalLines"
+
+    def get(journal_id, journal_line_id=nil)
+      get_child(journal_id, journal_line_id)
+    end
+  end
+end

data/lib/business_central/payment_method.rb

@@ -0,0 +1,10 @@
+##
+# Provides access to the /paymentMethods API
+#
+
+module BusinessCentral
+  class PaymentMethod < BusinessCentral::Base
+    API_OBJECT = "paymentMethods"
+    SUPPORTED_METHODS = [:get, :create, :update, :delete]
+  end
+end

data/lib/business_central/payment_term.rb

@@ -0,0 +1,10 @@
+##
+# Provides access to the /paymentTerms API
+#
+
+module BusinessCentral
+  class PaymentTerm < BusinessCentral::Base
+    API_OBJECT = "paymentTerms"
+    SUPPORTED_METHODS = [:get, :create, :update, :delete]
+  end
+end

data/lib/business_central/picture.rb

@@ -0,0 +1,10 @@
+##
+# Provides access to the /pictures API
+#
+
+module BusinessCentral
+  class Picture < BusinessCentral::Base
+    API_OBJECT_PARENT = "items"
+    API_OBJECT = "picture"
+  end
+end