business-central 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aa79fbf2f11dba355ca4486b9bed998dc3a481aa2c52f66d311bf1525e3f8620
+  data.tar.gz: 13910cff1f4af8e26fe89921c1021e2799f074134ebb797163aff3aac863e510
+SHA512:
+  metadata.gz: 67aa6439003bd9b3ec1599a97cfd2b235af9c68c140cac188609c0e3d496aac0a67447548c7acb9eef4182d7888a14cf5996bfbb48584db08ed9fb7ac97a8c4e
+  data.tar.gz: b5dfd537dd2c023f71196d8960b9bcc5b8ae88115f62bb53c1840531862312689eaba558b5903d0979b2c87070203c80a85294b69078efc014eb0caadf3d8dd2

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,120 @@
+# Business Central API Library
+
+This library is designed to help ruby/rails based applications communicate with the publicly available API for dynamics 365 business central.
+
+If you are unfamiliar with the business central API, you should first read the documentation located at https://docs.microsoft.com/en-us/dynamics-nav/api-reference/v1.0/.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'business-central'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install business-central
+
+## Basic Usage
+
+This gem supports both authentication methods:
+
+https://docs.microsoft.com/en-us/dynamics-nav/api-reference/v1.0/endpoints-apis-for-dynamics
+
+### Basic Authentication:
+
+https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-develop-connect-apps#setting-up-basic-authentication
+
+```Ruby
+require 'business_central'
+
+client = BusinessCentral::Client.new(
+    username: '<username>',
+    password: '<password>',
+    url: '<url>'
+)
+
+# Find all vendors
+vendors = client.vendor(company_id: '3a502065-2a08-4c3b-9468-fb83642d3d3a').find_all
+
+# Find vendor by ID
+vendor = client.vendor(company_id: '3a502065-2a08-4c3b-9468-fb83642d3d3a').find_by_id('3f445b08-2ffd-4f9d-81a0-b82f0d9714c4')
+
+# Query vendor by display name
+vendor = client.vendor(company_id: '3a502065-2a08-4c3b-9468-fb83642d3d3a').where("displayName eq 'First Up Consultants'")
+
+# Create a new vendor
+vendor = client.vendor(company_id: '3a502065-2a08-4c3b-9468-fb83642d3d3a').create({ display_name: 'hello testing new vendor' })
+
+# Update an existing vendor by ID
+vendor = client.vendor(company_id: '3a502065-2a08-4c3b-9468-fb83642d3d3a').update('3f445b08-2ffd-4f9d-81a0-b82f0d9714c4', { phone_number: '1112' })
+
+# Delete a vendor
+client.vendor(company_id: '3a502065-2a08-4c3b-9468-fb83642d3d3a').destroy('f0730ada-b315-ea11-a813-000d3ad21e99')
+```
+
+### Oauth2 Authentication
+
+https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-develop-connect-apps#AAD
+
+```Ruby
+require 'business_central'
+
+# Create client - used to connect to the API
+client = BusinessCentral::Client.new(
+    tenant_id: '<tenant_id>',
+    application_id: '<application_id>',
+    secret_key: '<application_secret_key>',
+    url: '<url>'
+)
+
+# Controller endpoint 1
+client.authorize({ state: '1234' }, oauth_authorize_callback: redirect_url )
+
+# Redirect URL endpoint - safely store the token to be re-used later
+token = client.request_token(params[:code], oauth_token_callback: redirect_url)
+
+client.authorize_from_token(
+    token: token.token,
+    refresh_token: token.refresh_token,
+    expires_at: DateTime.current + 3600,
+    expires_in: 3600
+)
+
+# Find all vendors
+vendors = client.vendor(company_id: '3a502065-2a08-4c3b-9468-fb83642d3d3a').find_all
+
+# Find vendor by ID
+vendor = client.vendor(company_id: '3a502065-2a08-4c3b-9468-fb83642d3d3a').find_by_id('3f445b08-2ffd-4f9d-81a0-b82f0d9714c4')
+
+# Query vendor by display name
+vendor = client.vendor(company_id: '3a502065-2a08-4c3b-9468-fb83642d3d3a').where("displayName eq 'First Up Consultants'")
+
+# Create a new vendor
+vendor = client.vendor(company_id: '3a502065-2a08-4c3b-9468-fb83642d3d3a').create({ display_name: 'hello testing' })
+
+# Update an existing vendor by ID
+vendor = client.vendor(company_id: '3a502065-2a08-4c3b-9468-fb83642d3d3a').update('3f445b08-2ffd-4f9d-81a0-b82f0d9714c4', { phone_number: '1112' })
+
+# Delete a vendor
+client.vendor(company_id: '3a502065-2a08-4c3b-9468-fb83642d3d3a').destroy('f0730ada-b315-ea11-a813-000d3ad21e99')
+```
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `rake test` to run the tests.
+
+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 tags, 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/JDrizzy/business-central.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/business_central.rb

@@ -0,0 +1,22 @@
+require 'oauth2'
+require 'oauth2/error'
+require 'net/http'
+require 'json'
+
+require 'core_ext/string'
+
+require 'business_central/object/helper'
+require 'business_central/object/base'
+require 'business_central/object/validation'
+require 'business_central/object/response'
+require 'business_central/object/request'
+
+require 'business_central/object/account'
+require 'business_central/object/company'
+require 'business_central/object/vendor'
+require 'business_central/object/item'
+require 'business_central/object/purchase_invoice'
+require 'business_central/object/purchase_invoice_line'
+
+require 'business_central/exceptions'
+require 'business_central/client'

data/lib/business_central/client.rb

@@ -0,0 +1,94 @@
+module BusinessCentral
+  class Client
+    extend BusinessCentral::Object::Helper
+
+    DEFAULT_URL = 'https://api.businesscentral.dynamics.com/v1.0/api/beta'.freeze
+
+    attr_reader :tenant_id,
+                :username,
+                :password,
+                :application_id,
+                :secret_key,
+                :url,
+                :oauth2_client
+
+    alias_method :access_token, :oauth2_client
+
+    object :account
+    object :company
+    object :vendor
+    object :purchase_invoice
+    object :purchase_invoice_line
+    object :item
+
+    def initialize(options = {})
+      opts = options.dup
+      @tenant_id = opts.delete(:tenant_id)
+      @username = opts.delete(:username)
+      @password = opts.delete(:password)
+      @url = opts.delete(:url) || DEFAULT_URL
+      @application_id = opts.delete(:application_id)
+      @secret_key = opts.delete(:secret_key)
+    end
+
+    def authorize(params = {}, oauth_authorize_callback: '')
+      params[:redirect_uri] = oauth_authorize_callback
+      begin
+        oauth2_client.auth_code.authorize_url(params)
+      rescue Oauth2::Error => error
+        handle_error(error)
+      end
+    end
+
+    def request_token(code = '', oauth_token_callback: '')
+      begin
+        oauth2_client.auth_code.get_token(code, redirect_uri: oauth_token_callback)
+      rescue OAuth2::Error => error
+        handle_error(error)
+      end
+    end
+
+    def authorize_from_token(token: '', refresh_token: '', expires_at: nil, expires_in: nil)
+      @oauth2_client = OAuth2::AccessToken.new(
+        oauth2_client,
+        token,
+        refresh_token: refresh_token,
+        expires_at: expires_at,
+        expires_in: expires_in,
+      )
+    end
+
+    def refresh_token
+      @oauth2_client.refresh!
+    end
+
+    private
+
+    def oauth2_client
+      if @oauth2_client.nil?
+        @oauth2_client = OAuth2::Client.new(
+          @application_id,
+          @secret_key,
+          {
+            site: "https://login.windows.net/#{@tenant_id}",
+            authorize_url: 'oauth2/authorize?resource=https://api.businesscentral.dynamics.com',
+            token_url: 'oauth2/token?resource=https://api.businesscentral.dynamics.com'
+          }
+        )
+      end
+        
+      return @oauth2_client
+    end
+
+    def handle_error(error)
+      if error.code.present?
+        case error.code
+          when 'invalid_client'
+            raise InvalidClientException.new
+        end
+      else
+        raise ApiException.new(error.message)
+      end
+    end
+  end
+end

data/lib/business_central/exceptions.rb

@@ -0,0 +1,55 @@
+module BusinessCentral
+
+  class BusinessCentralError < StandardError; end
+
+  class InvalidClientException < BusinessCentralError
+    def message
+      'Invalid application setup'
+    end
+  end
+
+  class ApiException < BusinessCentralError
+    def initialize(message)
+      @message = message
+    end
+
+    def message
+      @message
+    end
+  end
+
+  class CompanyNotFoundException < BusinessCentralError
+    def message
+      'Company not found'
+    end
+  end
+
+  class UnauthorizedException < BusinessCentralError
+    def message
+      'Unauthorized - The credentials provided are incorrect'
+    end
+  end
+
+  class InvalidObjectException < BusinessCentralError
+    def initialize(errors)
+      @errors = errors
+    end
+
+    def message
+      @errors.each do |error|
+        "#{error[:field]} - #{error[:message]}"
+      end
+    end
+  end
+
+  class NoSupportedMethod < BusinessCentralError
+    def initialize(method, allowed_methods)
+      @method = method
+      @allowed_methods = allowed_methods
+    end
+
+    def message
+      "#{method} method is currently not support. Allowed methods are: #{allowed_methods.join(', ')}"
+    end
+  end
+end

data/lib/business_central/object/account.rb

@@ -0,0 +1,11 @@
+module BusinessCentral
+  module Object
+    class Account < Base
+      OBJECT = 'accounts'.freeze
+
+      OBJECT_METHODS = [
+        :get
+      ].freeze
+    end
+  end
+end

data/lib/business_central/object/base.rb

@@ -0,0 +1,105 @@
+module BusinessCentral
+  module Object
+    class Base
+      attr_reader :client,
+                  :company_id,
+                  :parent_path,
+                  :path,
+                  :errors
+
+      def initialize(client, args = {})
+        @client = client
+        @company_id = args[:company_id] if !args.nil?
+        @parent_path = []
+        @path = ''
+        @errors = []
+      end
+
+      def find_all
+        if method_supported?(:get)
+          Request.get(@client, build_url(parent_path: @parent_path, child_path: object_name))
+        else
+          raise BusinessCentral::NoSupportedMethod.new(:get, object_methods)
+        end
+      end
+
+      def find_by_id(id)
+        if method_supported?(:get)
+          Request.get(@client, build_url(parent_path: @parent_path, child_path: object_name, child_id: id))
+        else
+          raise BusinessCentral::NoSupportedMethod.new(:get, object_methods)
+        end
+      end
+
+      def where(query = '')
+        if method_supported?(:get)
+          Request.get(@client, build_url(parent_path: @parent_path, child_path: object_name, filter: query))
+        else
+          raise BusinessCentral::NoSupportedMethod.new(:get, object_methods)
+        end
+      end
+
+      def create(params = {})
+        if method_supported?(:post)
+          if Validation.new(object_validation, params).valid?
+            Request.post(@client, build_url(parent_path: @parent_path, child_path: object_name), params)
+          end
+        else
+          raise BusinessCentral::NoSupportedMethod.new(:post, object_methods)
+        end
+      end
+
+      def update(id, params = {})
+        if method_supported?(:patch)
+          object = find_by_id(id)
+          if Validation.new(object_validation, params).valid?
+            Request.patch(@client, build_url(parent_path: @parent_path, child_path: object_name, child_id: id), object[:etag], params)
+          end
+        else
+          raise BusinessCentral::NoSupportedMethod.new(:patch, object_methods)
+        end
+      end
+
+      def destroy(id)
+        if method_supported?(:delete)
+          object = find_by_id(id)
+          Request.delete(@client, build_url(parent_path: @parent_path, child_path: object_name, child_id: id), object[:etag])
+        else
+          raise BusinessCentral::NoSupportedMethod.new(:delete, object_methods)
+        end
+      end
+
+      private
+
+      def object_name
+        self.class.const_get(:OBJECT)
+      end
+
+      def object_validation
+        self.class.const_get(:OBJECT_VALIDATION)
+      end
+
+      def object_methods
+        self.class.const_get(:OBJECT_METHODS)
+      end
+
+      def method_supported?(method)
+        return true if object_methods.include?(method)
+        return false
+      end
+
+      def build_url(parent_path: [], child_path: '', child_id: '', filter: '')
+        url_builder(parent_path, child_path, child_id, filter)
+      end
+
+      def url_builder(parent_path = [], child_path = '', child_id = '', filter = '')
+        url = @client.url
+        url += parent_path.map { |parent| "/#{parent[:path]}(#{parent[:id]})" }.join('') if !parent_path.empty?
+        url += "/#{child_path}" if !child_path.blank?
+        url += "(#{child_id})" if !child_id.blank?
+        url += "?$filter=#{filter}" if !filter.blank?
+        return url
+      end
+    end
+  end
+end

data/lib/business_central/object/company.rb

@@ -0,0 +1,11 @@
+module BusinessCentral
+  module Object
+    class Company < Base
+      OBJECT = 'companies'.freeze
+
+      OBJECT_METHODS = [
+        :get
+      ].freeze
+    end
+  end
+end