4me-sdk 1.1.8 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aba8de45bcc385f1f8ffedfce680f58cb5c73865510798712d7d8c382ecbd9bf
-  data.tar.gz: 1ffb444710f94ad590aa4943589465e028ad7cf1957bd5546fd93fe158871c6e
+  metadata.gz: 32cfcbac334dbc605b6488e54db56eb8c7db3dfca80724b08114affc264d4d59
+  data.tar.gz: ed44080e2df04693b32d62bd0a0086511af32301ba6e5d4a4e401ba0ab4d70f1
 SHA512:
-  metadata.gz: bdd2c6e55c547a2b13ca893a73e3167d77adee143e53e396b48d8712cfb8d7e148f0f3b10090c3b20691e22b20ddad4a1593d6f8e374880a98c9f8b71abfbe85
-  data.tar.gz: d63bc178ea462a8b4691ad2d63c25ca48ae5735820d398047dfe98ff450be1a6d3f6c8aa8e27c30829afb9753b5213a6f55c0539d1ba03f134908ea8a59ae4f3
+  metadata.gz: 0b4d62a29b08e73e7afce649acbccf27f3192f46d50b533e02429e0da45f3f1c99ccd5201343da550c3a7f2561d27e732a39c22794fb78f8f182831ec42a97f7
+  data.tar.gz: '08c618e5b35ec1a7bc3a47e5800b64da25a992475ccc7fa5f99d8e781b4b724a3caf32dbf0936d8ca79d244fac2a4c5ddb9facd5be06893c867f7d97a8dbc6fd'

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.8)
+    4me-sdk (2.0.0.pre.rc.2)
       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.5)
-    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.2019.0331)
-    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.17.3
+   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,20 @@ 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
+* _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, ... 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: `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. 
+* _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
@@ -70,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]
 ```
@@ -84,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:
 ```
@@ -105,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:
 ```
@@ -123,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
@@ -141,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:
 ```
@@ -198,39 +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')
+  ]
 })
 ```
 
-It is also possible to add inline attachments as follows:
-```
-response = Sdk4me::Client.new.put('requests/416621', {
-  note: 'Here is some inspiration for you: [attachment:/tmp/images/puppy.png]'
-})
-```
-Note that only images are accepted as inline attachments.
-
-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
@@ -243,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')
@@ -255,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
@@ -277,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))
@@ -289,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'
@@ -314,7 +315,7 @@ Note that blocking for the export to finish is recommended as you will get direc
 
 ### Blocking
 
-When the currently used API token hits the [4me rate limiter](http://developer.4me.com/v1/#rate-limiting) a HTTP 429 response is returned that specifies after how many seconds the rate limit will be lifted.
+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.
 
 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:
 ```
@@ -336,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.
 
@@ -347,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,10 +5,11 @@ 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
@@ -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