4me-sdk 1.1.5 → 2.0.0.pre.rc.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5709d9ce126fa6349fdff96ab4a2dd1c80b8653a
-  data.tar.gz: 56ea4d39c7dce6e5c0578f0eb5ab1bbeb154622d
+SHA256:
+  metadata.gz: 4c4c1ac14f3525802639a4aa78223d0635533ffee6527fed0a02e9f8b41aca54
+  data.tar.gz: 5e8b18fa02b940a0883b2ed6349a619cda9048201c87c4d953f53e373e64d88f
 SHA512:
-  metadata.gz: 754794a8253b590ddfd4064d2d96e9bae96597ab89c0169c6ebdb7fc8db4dd9035e7a0770be6f6644cff362a9f0dc5e061cb3992e15e6502556921bbdd997c5a
-  data.tar.gz: 80eaad3b45968a8ca3e1ce3afa4a6750c74105ba188122e1bcaf800ea87c64ab63c88893d70ee32793bf8bc19b22a38f5cec830935c153a03ccb978c83fb1607
+  metadata.gz: 5e0752a3cac273d81a7cafa7d43ca5a69088db6143418a9bb70b6a95f1111db422d8eb03d8f669f5d74efd1f0e05d2004f284f21e173605da0f4f3fcb601d62b
+  data.tar.gz: 41079af50a9db8a791614849197a5d5aee2049d1b2f9900c345802ff1a6439869f86f9f341309883cfe2c0233c590f352b1ef4c9f5ba81f4cf7506183d95c139

data/4me-sdk.gemspec

@@ -1,5 +1,4 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'sdk4me/client/version'
 
@@ -7,34 +6,34 @@ Gem::Specification.new do |spec|
   spec.name                  = '4me-sdk'
   spec.version               = Sdk4me::Client::VERSION
   spec.platform              = Gem::Platform::RUBY
-  spec.required_ruby_version = '>= 2.0.0'
+  spec.required_ruby_version = '>= 2.5.0'
   spec.authors               = ['4me']
-  spec.email                 = %q{developers@4me.com}
-  spec.description           = %q{SDK for accessing the 4me API}
-  spec.summary               = %q{The official 4me SDK for Ruby. Provides easy access to the APIs found at https://developer.4me.com}
-  spec.homepage              = %q{https://github.com/code4me/4me-sdk-ruby}
+  spec.email                 = 'developers@4me.com'
+  spec.description           = 'SDK for accessing the 4me REST API'
+  spec.summary               = 'The official 4me SDK for Ruby. Provides easy access to the REST APIs found at https://developer.4me.com'
+  spec.homepage              = 'https://github.com/code4me/4me-sdk-ruby'
   spec.license               = 'MIT'
 
-  spec.files = Dir.glob('lib/**/*') + %w(
+  spec.files = Dir.glob('lib/**/*') + %w[
     LICENSE
     README.md
     Gemfile
     Gemfile.lock
     4me-sdk.gemspec
-  )
-  spec.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  ]
+  spec.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
   spec.test_files    = `git ls-files -- {test,spec}/*`.split("\n")
   spec.require_paths = ['lib']
   spec.rdoc_options = ['--charset=UTF-8']
 
-  spec.add_runtime_dependency 'gem_config', '>=0.3'
   spec.add_runtime_dependency 'activesupport', '>= 4.2'
+  spec.add_runtime_dependency 'gem_config', '>=0.3'
   spec.add_runtime_dependency 'mime-types', '>= 3.0'
 
   spec.add_development_dependency 'bundler', '~> 1'
   spec.add_development_dependency 'rake', '~> 12'
   spec.add_development_dependency 'rspec', '~> 3.3'
-  spec.add_development_dependency 'webmock', '~> 2'
+  spec.add_development_dependency 'rubocop', '>= 0.49.0'
   spec.add_development_dependency 'simplecov', '~> 0'
-
+  spec.add_development_dependency 'webmock', '~> 3'
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    4me-sdk (1.1.5)
+    4me-sdk (2.0.0.pre.rc.1)
       activesupport (>= 4.2)
       gem_config (>= 0.3)
       mime-types (>= 3.0)
@@ -9,55 +9,73 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (5.2.2)
+    activesupport (6.0.3.4)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
-    addressable (2.5.2)
-      public_suffix (>= 2.0.2, < 4.0)
-    concurrent-ruby (1.1.4)
-    crack (0.4.3)
-      safe_yaml (~> 1.0.0)
-    diff-lcs (1.3)
-    docile (1.3.1)
-    gem_config (0.3.1)
-    hashdiff (0.3.7)
-    i18n (1.5.1)
+      zeitwerk (~> 2.2, >= 2.2.2)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    ast (2.4.1)
+    concurrent-ruby (1.1.7)
+    crack (0.4.4)
+    diff-lcs (1.4.4)
+    docile (1.3.2)
+    gem_config (0.3.2)
+    hashdiff (1.0.1)
+    i18n (1.8.5)
       concurrent-ruby (~> 1.0)
-    json (2.1.0)
-    mime-types (3.2.2)
+    mime-types (3.3.1)
       mime-types-data (~> 3.2015)
-    mime-types-data (3.2018.0812)
-    minitest (5.11.3)
-    public_suffix (3.0.3)
-    rake (12.3.1)
-    rspec (3.8.0)
-      rspec-core (~> 3.8.0)
-      rspec-expectations (~> 3.8.0)
-      rspec-mocks (~> 3.8.0)
-    rspec-core (3.8.0)
-      rspec-support (~> 3.8.0)
-    rspec-expectations (3.8.2)
+    mime-types-data (3.2020.1104)
+    minitest (5.14.2)
+    parallel (1.19.2)
+    parser (2.7.2.0)
+      ast (~> 2.4.1)
+    public_suffix (4.0.6)
+    rainbow (3.0.0)
+    rake (12.3.3)
+    regexp_parser (1.8.2)
+    rexml (3.2.4)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.0)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-mocks (3.8.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-support (3.8.0)
-    safe_yaml (1.0.4)
-    simplecov (0.16.1)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.0)
+    rubocop (0.93.1)
+      parallel (~> 1.10)
+      parser (>= 2.7.1.5)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8)
+      rexml
+      rubocop-ast (>= 0.6.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (1.1.1)
+      parser (>= 2.7.1.5)
+    ruby-progressbar (1.10.1)
+    simplecov (0.19.1)
       docile (~> 1.1)
-      json (>= 1.8, < 3)
-      simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.2)
+      simplecov-html (~> 0.11)
+    simplecov-html (0.12.3)
     thread_safe (0.3.6)
-    tzinfo (1.2.5)
+    tzinfo (1.2.7)
       thread_safe (~> 0.1)
-    webmock (2.3.2)
+    unicode-display_width (1.7.0)
+    webmock (3.9.4)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
-      hashdiff
+      hashdiff (>= 0.4.0, < 2.0.0)
+    zeitwerk (2.4.1)
 
 PLATFORMS
   ruby
@@ -67,8 +85,9 @@ DEPENDENCIES
   bundler (~> 1)
   rake (~> 12)
   rspec (~> 3.3)
+  rubocop (>= 0.49.0)
   simplecov (~> 0)
-  webmock (~> 2)
+  webmock (~> 3)
 
 BUNDLED WITH
-   1.16.2
+   1.16.6

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 https://code.4me.com
+Copyright (c) 2020 https://code.4me.com
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,6 +1,6 @@
 # Sdk4me::Client
 
-Client for accessing the [4me REST API](http://developer.4me.com/v1/)
+Client for accessing the [4me REST API](https://developer.4me.com/v1/)
 
 ## Installation
 
@@ -22,7 +22,7 @@ Or install it yourself as:
 
 ```
 Sdk4me.configure do |config|
-  config.api_token = 'd41f5868feb65fc87fa2311a473a8766ea38bc40'
+  config.access_token = 'd41f5868feb65fc87fa2311a473a8766ea38bc40'
   config.account = 'my-sandbox'
   config.logger = Rails.logger
   ...
@@ -32,18 +32,21 @@ end
 All options available:
 
 * _logger_:         The [Ruby Logger](http://www.ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html) instance, default: `Logger.new(STDOUT)`
-* _host_:           The [4me API host](http://developer.4me.com/v1/#service-url), default: 'https://api.4me.com'
-* _api_version_:    The [4me API version](http://developer.4me.com/v1/#service-url), default: 'v1'
-* _api_token_:      (**required**) The [4me API token](http://developer.4me.com/v1/#api-tokens)
-* _account_:        Specify a [different account](http://developer.4me.com/v1/#multiple-accounts) to work with
-* _source_:         The [source](http://developer.4me.com/v1/general/source/) used when creating new records
-* _max_retry_time_: maximum nr of seconds to wait for server to respond (default = 5400 = 1.5 hours)<br/>
+* _host_:           The [4me REST API host](https://developer.4me.com/v1/#service-url), default: 'https://api.4me.com'
+* _api_version_:    The [4me REST API version](https://developer.4me.com/v1/#service-url), default: 'v1'
+* _access_token_:   (**required**) The [4me access token](https://developer.4me.com/v1/#authentication)
+* _api_token_:      (**deprecated**) The [4me API token](https://developer.4me.com/v1/#api-tokens)
+* _account_:        Specify a [different account](https://developer.4me.com/v1/#multiple-accounts) to work with
+* _source_:         The [source](https://developer.4me.com/v1/general/source/) used when creating new records
+* _user_agent_:     The User-Agent header of each request. Defaults to 4me-sdk-ruby/(version)
+* _max_retry_time_: maximum nr of seconds to retry a request on a failed response (default = 300 = 5 minutes)<br/>
   The sleep time between retries starts at 2 seconds and doubles after each retry, i.e.
-  2, 6, 18, 54, 162, 486, 1458, 4374, 13122, ... seconds.<br/>
+  2, 6, 18, 54, 162, 486, 1458, ... seconds.<br/>
   Set to 0 to prevent retries.
 * _read_timeout_:   [HTTP read timeout](http://ruby-doc.org/stdlib-2.0.0/libdoc/net/http/rdoc/Net/HTTP.html#method-i-read_timeout-3D) in seconds (default = 25)
-* _block_at_rate_limit_: Set to `true` to block the request until the [rate limit](http://developer.4me.com/v1/#rate-limiting) is lifted, default: `false`<br/>
-  The `Retry-After` header is used to compute when the retry should be performed. If that moment is later than the _max_retry_time_ the request will not be blocked and the throttled response is returned. 
+* _block_at_rate_limit_: Set to `true` to block the request until the [rate limit](https://developer.4me.com/v1/#rate-limiting) is lifted, default: `true`<br/>
+  The `Retry-After` header is used to compute when the retry should be performed. If that moment is later than the _max_throttle_time_ the request will not be blocked and the throttled response is returned.
+* _max_throttle_time_: maximum nr of seconds to retry a request on a rate limiter (default = 3660 = 1 hour and 1 minute)<br/>
 * _proxy_host_:     Define in case HTTP traffic needs to go through a proxy
 * _proxy_port_:     Port of the proxy, defaults to 8080
 * _proxy_user_:     Proxy user
@@ -69,7 +72,7 @@ Minimal example:
 ```
 require 'sdk4me/client'
 
-client = Sdk4me::Client.new(api_token: '3a4e4590179263839...')
+client = Sdk4me::Client.new(access_token: '3a4e4590179263839...')
 response = client.get('me')
 puts response[:primary_email]
 ```
@@ -83,7 +86,7 @@ response = Sdk4me::Client.new.get('organizations/4321')
 puts response[:name]
 ```
 
-By default this call will return all [fields](http://developer.4me.com/v1/organizations/#fields) of the Organization.
+By default this call will return all [fields](https://developer.4me.com/v1/organizations/#fields) of the Organization.
 
 The fields can be accessed using *symbols* and *strings*, and it is possible chain a number of keys in one go:
 ```
@@ -104,8 +107,8 @@ end
 puts "Found #{count} organizations"
 ```
 
-By default this call will return all [collection fields](http://developer.4me.com/v1/organizations/#collection-fields) for each Organization.
-For more fields, check out the [field selection](http://developer.4me.com/v1/general/field_selection/#collection-of-resources) documentation.
+By default this call will return all [collection fields](https://developer.4me.com/v1/organizations/#collection-fields) for each Organization.
+For more fields, check out the [field selection](https://developer.4me.com/v1/general/field_selection/#collection-of-resources) documentation.
 
 The fields can be accessed using *symbols* and *strings*, and it is possible chain a number of keys in one go:
 ```
@@ -122,7 +125,7 @@ Note that an `Sdk4me::Exception` could be thrown in case one of the API requests
 
 The `each` method [described above](#browse-through-a-collection-of-records) is the preferred way to work with collections of data.
 
-If you really want to [paginate](http://developer.4me.com/v1/general/pagination/) yourself, the `get` method is your friend.
+If you really want to [paginate](https://developer.4me.com/v1/general/pagination/) yourself, the `get` method is your friend.
 
 ```
 @client = Sdk4me::Client.new
@@ -140,8 +143,8 @@ next_page  = @client.get(response.pagination_link(:next))
 last_page  = @client.get(response.pagination_link(:last))
 ```
 
-By default this call will return all [collection fields](http://developer.4me.com/v1/organizations/#collection-fields) for each Organization.
-For more fields, check out the [field selection](http://developer.4me.com/v1/general/field_selection/#collection-of-resources) documentation.
+By default this call will return all [collection fields](https://developer.4me.com/v1/organizations/#collection-fields) for each Organization.
+For more fields, check out the [field selection](https://developer.4me.com/v1/general/field_selection/#collection-of-resources) documentation.
 
 The fields can be accessed using *symbols* and *strings*, and it is possible chain a number of keys in one go:
 ```
@@ -197,31 +200,38 @@ end
 Make sure to validate the success by calling `response.valid?` and to take appropriate action in case the response is not valid.
 
 
-### Note Attachments
+### Attachments
 
-To add attachments to a note is rather tricky when done manually as it involves separate file uploads to Amazon S3 and sending
-confirmations back to 4me.
+Adding attachments and inline images to rich text fields is a two-step process.
+First upload the attachments to 4me, and then refer to the uploaded attachments
+when creating or updating a 4me record.
 
-To make it easy, a special `attachments` parameter can be added when using the `post` or `put` method when the `note` field is available.
+To make this process easy, refer to the files using string filepaths or
+File references:
 
 ```
 response = Sdk4me::Client.new.put('requests/416621', {
   status: 'waiting_for_customer',
-  note: 'Please complete the attached forms and reassign the request back to us.',
-  attachments: ['/tmp/forms/Inventory.xls', '/tmp/forms/PersonalData.xls']
+  note: 'Please complete the attached forms and assign the request back to us.',
+  note_attachments: [
+    '/tmp/forms/README.txt',
+    File.open('/tmp/forms/PersonalData.xls', 'rb')
+  ]
 })
 ```
 
-If an attachment upload fails, the errors are logged but the `post` or `put` request will still be sent to 4me without the
-failed attachments. To receive exceptions add `attachments_exception: true` to the data.
+It is also possible to add inline attachments. Refer to attachments by their
+array index, with the index being zero-based. Text can only refer to inline
+images in its own attachments collection. For example:
 
 ```
 begin
-  response = Sdk4me::Client.new.put('requests/416621', {
+  data = {
     status: 'waiting_for_customer',
-    note: 'Please complete the attached forms and reassign the request back to us.',
-    attachments: ['/tmp/forms/Inventory.xls', '/tmp/forms/PersonalData.xls']
-  })
+    note: 'See [note_attachments: 0] and [note_attachments: 1]',
+    note_attachments: ['/tmp/info.png', '/tmp/help.png']
+  }
+  response = Sdk4me::Client.new.put('requests/416621', data)
   if response.valid?
     puts "Request #{response[:id]} updated and attachments added to the note"
   else
@@ -234,7 +244,7 @@ end
 
 ### Importing CSV files
 
-4me also provides an [Import API](http://developer.4me.com/v1/import/). The 4me SDK Client can be used to upload files to that API.
+4me also provides an [Import API](https://developer.4me.com/v1/import/). The 4me SDK Client can be used to upload files to that API.
 
 ```
 response = Sdk4me::Client.new.import('\tmp\people.csv', 'people')
@@ -246,9 +256,9 @@ end
 
 ```
 
-The second argument contains the [import type](http://developer.4me.com/v1/import/#parameters).
+The second argument contains the [import type](https://developer.4me.com/v1/import/#parameters).
 
-It is also possible to [monitor the progress](http://developer.4me.com/v1/import/#import-progress) of the import and block until the import is complete. In that case you will need to add some exception handling to your code.
+It is also possible to [monitor the progress](https://developer.4me.com/v1/import/#import-progress) of the import and block until the import is complete. In that case you will need to add some exception handling to your code.
 
 ```
 begin
@@ -268,7 +278,7 @@ Note that blocking for the import to finish is required when you import multiple
 
 ### Exporting CSV files
 
-4me also provides an [Export API](http://developer.4me.com/v1/export/). The 4me SDK Client can be used to download (zipped) CSV files using that API.
+4me also provides an [Export API](https://developer.4me.com/v1/export/). The 4me SDK Client can be used to download (zipped) CSV files using that API.
 
 ```
 response = Sdk4me::Client.new.export(['people', 'people_contact_details'], DateTime.new(2012,03,30,23,00,00))
@@ -280,10 +290,10 @@ end
 
 ```
 
-The first argument contains the [export types](http://developer.4me.com/v1/export/#parameters).
+The first argument contains the [export types](https://developer.4me.com/v1/export/#parameters).
 The second argument is optional and limits the export to all changed records since the given time.
 
-It is also possible to [monitor the progress](http://developer.4me.com/v1/export/#export-progress) of the export and block until the export is complete. In that case you will need to add some exception handling to your code.
+It is also possible to [monitor the progress](https://developer.4me.com/v1/export/#export-progress) of the export and block until the export is complete. In that case you will need to add some exception handling to your code.
 
 ```
 require 'open-uri'
@@ -305,10 +315,17 @@ Note that blocking for the export to finish is recommended as you will get direc
 
 ### Blocking
 
-By default all actions on the 4me SDK Client will block until the 4me API is accessible, see the _max_retry_time_ option in the [configuration](#configuration). This is especially helpfull for flaky internet connections.
+When the currently used API token hits the [4me rate limiter](https://developer.4me.com/v1/#rate-limiting) a HTTP 429 response is returned that specifies after how many seconds the rate limit will be lifted.
 
-By setting the _block_at_rate_limit_ to `true` in the [configuration](#configuration) all actions will also block in case the [rate limit](http://developer.4me.com/v1/#rate-limiting) is reached. The action is retried every 5 minutes until the [rate limit](http://developer.4me.com/v1/#rate-limiting) is lifted again, which might take up to 1 hour.
+If that time lies within the _max_throttle_time_ the 4me SDK Client will wait and retry the action, if not, the throttled response will be returned. You can verify if a response was throttled using:
+```
+response = client.get('me')
+puts response.throttled?
+```
+
+By setting the _block_at_rate_limit_ to `false` in the [configuration](#configuration) the 4me SDK Client will never wait when a rate limit is hit.
 
+Note that 4me has different rate limiters. If the intention is to only wait when the short-burst (max 20 requests in 2 seconds) rate limiter is hit, you could set the _max_throttle_time_ to e.g. 5 seconds.
 
 ### Translations
 
@@ -320,7 +337,7 @@ When exporting translations, the _locale_ parameter is required:
 
 ### Exception handling
 
-The standard methods `get`, `post`, `put` and `delete` will always return a Response with an [error message](http://developer.4me.com/v1/#http-status-codes) in case something went wrong.
+The standard methods `get`, `post`, `put` and `delete` will always return a Response with an [error message](https://developer.4me.com/v1/#http-status-codes) in case something went wrong.
 
 By calling `response.valid?` you will know if the action succeeded or not, and `response.message` provides additinal information in case the response was invalid.
 
@@ -331,3 +348,11 @@ puts response.message
 ```
 
 The methods `each` and `import` may throw an `Sdk4me::Exception` in case something failed, see the examples above.
+
+## Changelog
+
+The changelog is available [here](CHANGELOG.md).
+
+## Copyright
+
+Copyright (c) 2020 4me, Inc. See [LICENSE](LICENSE) for further details.

data/lib/sdk4me.rb

@@ -5,19 +5,20 @@ module Sdk4me
   include GemConfig::Base
 
   with_configuration do
-    has :logger, classes: ::Logger, default: ::Logger.new(STDOUT)
+    has :logger, classes: ::Logger, default: ::Logger.new($stdout)
 
     has :host, classes: String, default: 'https://api.4me.com'
     has :api_version, values: ['v1'], default: 'v1'
+    has :access_token, classes: String
     has :api_token, classes: String
 
     has :account, classes: String
     has :source, classes: String
 
-    has :max_retry_time, classes: Integer, default: 5400
+    has :max_retry_time, classes: Integer, default: 300
     has :read_timeout, classes: Integer, default: 25
-    has :block_at_rate_limit, classes: [TrueClass, FalseClass], default: false
-
+    has :block_at_rate_limit, classes: [TrueClass, FalseClass], default: true
+    has :max_throttle_time, classes: Integer, default: 3660
     has :proxy_host, classes: String
     has :proxy_port, classes: Integer, default: 8080
     has :proxy_user, classes: String
@@ -30,8 +31,9 @@ module Sdk4me
     configuration.logger
   end
 
-  class Exception < ::Exception; end # ::Sdk4me::Exception class
-
-  class UploadFailed < Exception; end # ::Sdk4me::UploadFailed class
+  class Exception < ::Exception
+  end
 
-end
+  class UploadFailed < Exception
+  end
+end