jortt 2.0.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 77c2bef2b81e18794d1f60872ba00fb5a267d2e1
-  data.tar.gz: be437bdf4b8d419736c7d5a08f963931a1b70826
+SHA256:
+  metadata.gz: 4034de85abfce8b8e5116576441272434c1435d4d51c7f86a2c01d7f87da5506
+  data.tar.gz: 764eba179889e670fc8f0c1a7620dfcefdba8735612ef002c67c7ce4817eea66
 SHA512:
-  metadata.gz: 685dcfac26a6f566ec4f074f6e44908b219cd1e8c094fb4c3bb4bee0962879aee17feb09e086a16e704755434a08d0e96c68f55121a0d69a316dca9a80480b39
-  data.tar.gz: c7b5c30f5d1417acaecf3d736e0b9bf8fcdb985bdae26bd56abba674037ca445454b8da71e63fcb434197fe0a245f004b2956f1a2ca082057520bd416b97fb9d
+  metadata.gz: aaa6c20cfeedfdf18f2eeafa90e46ae7c8e0402bad48ad6b3849d10ca1caaa919697b7e7881e9333b41426cecd235f9f78206737c535f8f4e6ccafca92e7c96c
+  data.tar.gz: 022c967a77e8d5ac6db87ed7ba8eb4613de35d0ac62f09762476f2423e5a97333bcb5c7b4c28ac780595d0d9945e52a2e8fa401e1fe24c77cd941eafdf1ca596

data/.ruby-version

@@ -1 +1 @@
-2.1.5
+2.7.1

data/.travis.yml

@@ -1,7 +1,5 @@
 language: ruby
 rvm:
-  - 1.9.3
-  - 2.1.5
+  - 2.4.3
 script:
   - bundle exec rspec
-  - bundle exec rubocop

data/README.md

@@ -1,86 +1,122 @@
-# Freemle REST API client
+# Jortt REST API client
 
 [![Inline docs](
-http://inch-ci.org/github/jorttbv/jortr-ruby.svg?branch=master&style=flat
+http://inch-ci.org/github/jorttbv/jortt-ruby.svg?branch=master&style=flat
 )](http://inch-ci.org/github/jorttbv/jortt-ruby)
 [![Code Climate](
 http://img.shields.io/codeclimate/github/jorttbv/jortt-ruby.svg?style=flat
 )](https://codeclimate.com/github/jorttbv/jortt-ruby)
-[![Coverage Status](
-http://img.shields.io/coveralls/jorttbv/jortt-ruby.svg?style=flat
-)](https://coveralls.io/r/jorttbv/jortt-ruby)
+[![Code Coverage](
+https://codecov.io/github/jorttbv/jortt-ruby/coverage.svg?branch=master
+)](https://codecov.io/github/jorttbv/jortt-ruby?branch=master)
 [![Build Status](
 http://img.shields.io/travis/jorttbv/jortt-ruby.svg?style=flat
 )](https://travis-ci.org/jorttbv/jortt-ruby)
 
 A Ruby interface to the [Jortt](https://www.jortt.nl/) REST API.
 
-## Usage
+Check https://developer.jortt.nl/ for more info.
 
-Note: The client is still called Freemle for historic reasons. Name change on its way...
+> THIS VERSION IS FOR THE NEW OAUTH API. STILL ON THE LEGACY API? USE VERSION 4.x OF THIS GEM: [CLICK HERE](https://github.com/jorttbv/jortt-ruby/tree/v4.2.0)
 
-To create a freemle client:
+## Usage examples
+
+To create a jortt client:
 ```ruby
-freemle = Freemle.client(
-  app_name: "application-name-as-chosen-on-jortt.nl",
-  api_key: "api-key-as-provided-by-jortt.nl"
-)
+jortt = Jortt.client('<your-client-id>', '<your-client-secret>')
 ```
 
 ### Customers
 
-Accessing customers (`freemle.customers.search('Jortt')`) returns:
+All customers (`jortt.customers.index(page: 2)`) returns:
 ```ruby
 [{
-  company_name: 'Jortt',
-  address: {
-    street: "Transistorstraat 71C",
-    postal_code: "1322 CK",
-    city: "Almere",
-    country_code: "NL"
-  }
-},
-  company_name: 'ttroj',
-  address: {
-    street: "Jorttweg",
-    ...
-  }
+  "id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
+  "is_private": true,
+  "customer_name": "Jortt",
+  "address_street": "Rozengracht 75a",
+  ...
 }]
 ```
 
 Adding customers:
 ```ruby
-freemle.customers.create(
-  company_name: "Jortt B.V.",
-  attn: "Vibiemme", # Optional
-  extra_information: "The best cofee maker!", # Optional
-  address: {
-    street: "Transistorstraat 71C",
-    postal_code: "1322 CK",
-    city: "Almere",
-    country_code: "NL"
-  }
+jortt.customers.create(
+  "is_private": true,
+  "customer_name": "Jortt",
+  ...
 )
 ```
 
 ### Invoices
+Get invoices by ID (`jortt.invoices.get('934d59dd-76f6-4716-9e0f-82a618e1be21')`) returns:
+```ruby
+{
+  "invoice_id": "934d59dd-76f6-4716-9e0f-82a618e1be21",
+  "recipient": {
+    "company_name": "Zilverline B.V.",
+    "attn": null,
+    "address": {
+      "street": "Cruquisweg 109F",
+      "city": "Amsterdam",
+      "postal_code": "1111SX",
+      "country": {
+        "code": "NL",
+        "name": "Nederland"
+      }
+    },
+    "email": "ben@jortt.nl",
+    "customer_id": "e1c5e15b-e34e-423e-a291-4ed43226a190",
+    "extra_information": null,
+    ...
+  }
+  ...
+}
+```
+
+
+Searching invoices (`jortt.invoices.index(query: '202001-002')`) returns:
+```ruby
+[{
+  "id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
+  "invoice_status": "draft",
+  "customer_id": "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
+  "invoice_number": "202001-002",
+  "invoice_date": "2020-02-23",
+  ...
+}]
+
+```
+
 
 Adding invoices:
 ```ruby
-freemle.invoices.create(
-  customer_id: "123456789", # Optional
-  delivery_period: "31-12-1234", # Optional
-  reference: "my-reference", # Optional
+jortt.invoices.create(
+  customer_id: "f8fd3e4e-da1c-43a7-892f-1410ac13e38a",
+  invoice_date: "2020-02-23",
+  delivery_period: "2020-02-01",
+  payment_term: 14,
+  net_amounts: true,
+  send_method: "email",
+  introduction: "example",
+  remarks: "example",
+  payment_method: "pay_later",
   line_items: [
-    {vat: 21, amount: 1359.50, quantity: 1, description: "Scrum Training"}
-  ]
+    {
+      description: "this is a description example",
+      units: 3.14,
+      amount_per_unit: {
+        value: "365.00",
+        currency: "EUR"
+      },
+      vat: 21,
+      ledger_account_id: "f8fd3e4e-da1c-43a7-892f-1410ac13e38a"
+    }
+  ],
+  reference: "123"
 )
 ```
 
-## Documentation
-
-Check https://app.jortt.nl/api-documentatie for more info.
-
 ## Development
 
 ### Running tests
@@ -90,10 +126,12 @@ Check https://app.jortt.nl/api-documentatie for more info.
 ### Building the gem
 
 `rake build` and then `rake install` to test it locally (`irb` followed
-by `require 'freemle/client'` and do your stuff).
+by `require 'jortt/client'` and do your stuff).
 
 ### Releasing the gem
 
 Make a fix, commit and push. Make sure the build is green. Then bump the
-version (edit `lib/freemle/client/version.rb`). Now `rake release` and follow
+version (edit `lib/jortt/client/version.rb`). Now `rake release` and follow
 the instructions (you need a rubygems.org account and permissions ;-)).
+
+Otherwise `gem build jortt.gemspec` and `gem push jortt-[version].gem`.

data/Rakefile

@@ -1,4 +1,3 @@
-# encoding: UTF-8
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 

data/jortt.gemspec

@@ -1,15 +1,25 @@
 # coding: utf-8
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'freemle/client/version'
+require 'jortt/client/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'jortt'
-  spec.version       = Freemle::Client::VERSION
-  spec.authors       = ['Bob Forma', 'Steven Weller', 'Lars Vonk']
-  spec.email         = %w(bforma@zilverline.com suweller@zilverline.com lvonk@zilverline.com)
+  spec.version       = Jortt::Client::VERSION
+  spec.authors       = [
+    'Bob Forma',
+    'Michael Franken',
+    'Lars Vonk',
+    'Stephan van Diepen',
+  ]
+  spec.email         = [
+    'bforma@zilverline.com',
+    'mfranken@zilverline.com',
+    'lvonk@zilverline.com',
+    'svdiepen@zilverline.com',
+  ]
   spec.summary       = 'jortt.nl REST API client'
-  spec.homepage      = 'https://www.jortt.nl/api-documentatie'
+  spec.homepage      = 'https://app.jortt.nl/api-documentatie'
   spec.license       = 'MIT'
 
   spec.files         = `git ls-files -z`.split("\x0")
@@ -17,13 +27,14 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
-  spec.add_runtime_dependency 'rest-client', '~> 1.6'
+  spec.add_runtime_dependency 'rest-client', '~> 2.0'
+  spec.add_runtime_dependency 'oauth2', '~> 1.4.4'
 
-  spec.add_development_dependency 'bundler', '~> 1.0'
-  spec.add_development_dependency 'coveralls', '~> 0.7'
-  spec.add_development_dependency 'rake', '~> 10.0'
-  spec.add_development_dependency 'rspec', '~> 2.14'
-  spec.add_development_dependency 'webmock', '~> 1.17'
-  spec.add_development_dependency 'rubocop', '~> 0.24.1'
-  spec.add_development_dependency 'rubocop-rspec', '~> 1.1.0'
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'codecov', '~> 0.1'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.7'
+  spec.add_development_dependency 'rspec-its', '~> 1.2'
+  spec.add_development_dependency 'webmock', '~> 3.3'
+  spec.add_development_dependency 'vcr', '~> 6.0'
 end

data/lib/jortt.rb

@@ -0,0 +1,21 @@
+require 'jortt/client'
+require 'jortt/client/version'
+
+##
+# This module contains everything needed to setup a connection to the Jortt
+# API. It's only method returns a configured Jortt::Client.
+module Jortt
+
+  # Convenient way to initialize a jortt client.
+  #
+  # @see {Jortt::Client.initialize}
+  #
+  # @return [ Jortt::Client ] a new jortt client instance
+  #
+  # @since 1.0.1
+  def client(*args)
+    Jortt::Client.new(*args)
+  end
+  module_function :client
+
+end

data/lib/jortt/client.rb

@@ -0,0 +1,121 @@
+require 'oauth2'
+
+require 'jortt/client/error'
+require 'jortt/client/customers'
+require 'jortt/client/invoices'
+require 'jortt/client/ledger_accounts'
+
+module Jortt
+  ##
+  # This class is the main interface used to communicate with the Jortt API.
+  # It is by the {Jortt} module to create configured instances.
+  class Client
+    SITE = 'https://api.jortt.nl'
+    OAUTH_PROVIDER_URL = 'https://app.jortt.nl/oauth-provider/oauth'
+
+    attr_accessor :token
+
+    # Initialize a Jortt client.
+    #
+    # @example
+    #   Jortt::Client.new(
+    #     "my-client-id",
+    #     "my-client-secret"
+    #   )
+    #
+    # @params [ Hash ] opts Options for the client,
+    #   optionally including base_url.
+    #
+    # @return [ Jortt::Client ]
+    #
+    # @since 1.0.0
+    def initialize(id, secret, opts = {})
+      oauth_provider_url = opts[:oauth_provider_url] || OAUTH_PROVIDER_URL
+
+      client = OAuth2::Client.new(id, secret,
+        site: opts[:site] || SITE,
+        token_url: "#{oauth_provider_url}/token",
+        authorize_url: "#{oauth_provider_url}/authorize",
+        auth_scheme: :basic_auth
+      )
+
+      @token = client.client_credentials.get_token(scope: "invoices:read invoices:write customers:read customers:write")
+    end
+
+    # Access the customer resource to perform operations.
+    #
+    # @example
+    #   client.customers
+    #
+    # @return [ Jortt::Client::Customers ] entry to the customer resource.
+    #
+    # @since 1.0.0
+    def customers
+      @customers ||= Jortt::Client::Customers.new(self)
+    end
+
+    # Access the invoices resource to perform operations.
+    #
+    # @example
+    #   client.invoices
+    #
+    # @return [ Jortt::Client::Invoices ] entry to the invoice resource.
+    #
+    # @since 1.0.0
+    def invoices
+      @invoices ||= Jortt::Client::Invoices.new(self)
+    end
+
+    # Access the ledger_accounts resource.
+    #
+    # @example
+    #   client.ledger_accounts
+    #
+    # @return [ Jortt::Client::LedgerAccounts ] entry to the leger_accounts resource.
+    #
+    # @since 5.0.0
+    def ledger_accounts
+      Jortt::Client::LedgerAccounts.new(self)
+    end
+
+    def get(path, params = {})
+      handle_response { token.get(path, params: params) }
+    end
+
+    def post(path, params = {})
+      handle_response { token.post(path, params: params) }
+    end
+
+    def put(path, params = {})
+      handle_response { token.put(path, params: params) }
+    end
+
+    def delete(path)
+      handle_response { token.delete(path) }
+    end
+
+    def handle_response(&block)
+      response = yield
+      return true if response.status == 204
+      response.parsed.fetch('data')
+    rescue OAuth2::Error => e
+      raise Error.from_response(e.response)
+    end
+
+    def paginated(path, params = {})
+      page = 1
+
+      Enumerator.new do |yielder|
+        loop do
+          response = token.get(path, params: params.merge(page: page)).parsed
+          response['data'].each { |item| yielder << item }
+          break if response['_links']['next'].nil?
+          page += 1
+        end
+      end
+    rescue OAuth2::Error => e
+      raise Error.from_response(e.response)
+    end
+
+  end
+end

data/lib/jortt/client/customers.rb

@@ -0,0 +1,91 @@
+module Jortt # :nodoc:
+  class Client # :nodoc:
+    ##
+    # Exposes the operations available for a collection of customers.
+    #
+    # @see { Jortt::Client.customers }
+    class Customers
+      attr_accessor :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      ##
+      # Returns all customers using the GET /customers endpoint.
+      # https://developer.jortt.nl/#list-customers
+      #
+      # @example
+      #   client.customers.index(query: 'Jane')
+      #
+      def index(query: nil)
+        client.paginated('/customers', query: query)
+      end
+
+      ##
+      # Returns a customer using the GET /customers/{customer_id} endpoint.
+      # https://developer.jortt.nl/#get-customer-by-id
+      #
+      # @example
+      #   client.customers.show("9afcd96e-caf8-40a1-96c9-1af16d0bc804")
+      #
+      def show(id)
+        client.get("/customers/#{id}")
+      end
+
+      ##
+      # Creates a Customer using the POST /customers endpoint.
+      # https://developer.jortt.nl/#create-customer
+      #
+      # @example
+      #   client.customers.create(
+      #     is_private: false,
+      #     customer_name: 'Nuka-Cola Corporation',
+      #     address_street: 'Vault 11',
+      #     address_postal_code: '1111AA',
+      #     address_city: 'Mojave Wasteland'
+      #   )
+      #
+      def create(payload)
+        client.post('/customers', payload)
+      end
+
+      ##
+      # Updates a Customer using the PUT /customers/{customer_id} endpoint.
+      # https://developer.jortt.nl/#update-customer
+      #
+      # @example
+      #   client.customers.update(
+      #     "9afcd96e-caf8-40a1-96c9-1af16d0bc804",
+      #     { address_extra_information: 'foobar' }
+      #   )
+      #
+      def update(id, payload)
+        client.put("/customers/#{id}", payload)
+      end
+
+      ##
+      # Deletes a Customer using the DELETE /customers/{customer_id} endpoint.
+      # https://developer.jortt.nl/#delete-a-customer
+      #
+      # @example
+      #   client.customers.delete("9afcd96e-caf8-40a1-96c9-1af16d0bc804")
+      #
+      def delete(id)
+        client.delete("/customers/#{id}")
+      end
+
+      ##
+      # Send direct debit authorization to a Customer using POST /customers/{customer_id}/direct_debit_mandate.
+      # https://developer.jortt.nl/#send-direct-debit-authorization-to-a-customer
+      #
+      # @example
+      #   client.customers.direct_debit_mandate("9afcd96e-caf8-40a1-96c9-1af16d0bc804")
+      #
+
+      def direct_debit_mandate(id)
+        client.post("/customers/#{id}/direct_debit_mandate")
+      end
+    end
+  end
+end