4me-sdk 1.1.4 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 864b07c2b953a22cde7b603d2ca40e0c922af5ab
-  data.tar.gz: 191f083e0183d044f77c9872a3b28f6e3541bf24
+SHA256:
+  metadata.gz: dc85cfa0c6b08a248805e24e37b4fe0cde152c64d42443b72ca8db4e5cf2799a
+  data.tar.gz: ebfe8f4d1e32e791ef5d109ef6934aa3fa585a60df8cd1f4f000073993cc9a2f
 SHA512:
-  metadata.gz: 161e613f6c9e5af777051f09aad8c83cd4ade36395550e0c4da63c8d7ee4a399f161aadbd0c3ee965db44864c2faa3ed4f336017b98e85b9196c6a0ee8844d13
-  data.tar.gz: 348aa6bb7536b81c6cf0642e0b7376c3aea935d88dc6743af82cdf563b023d92f82773f72ef500c44458a448eb96b0027bce74d9e4b79f7f9c2901f3483bb013
+  metadata.gz: e05769acff36f8c0ffc6758d4078217b4af13cd969814ee85699d0e84951c6b9d34d6d4b2d7fb0fddb2577a2a03b4aeda3b7c687d0ec62916ef8e712ce5224cc
+  data.tar.gz: 6cac609bb11b34d97086e701701d7f664ca24500cca943a948e7ce42d7650e2dd2c8f14a0a348dd6d0b2295c90257d1a39411ae0f2e7a8a67202396edf8dc31b

data/4me-sdk.gemspec

@@ -34,7 +34,7 @@ Gem::Specification.new do |spec|
   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 'webmock', '~> 3'
   spec.add_development_dependency 'simplecov', '~> 0'
 
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    4me-sdk (1.1.4)
+    4me-sdk (1.2.0)
       activesupport (>= 4.2)
       gem_config (>= 0.3)
       mime-types (>= 3.0)
@@ -9,28 +9,27 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (5.2.1)
+    activesupport (5.2.2)
       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.3)
-    crack (0.4.3)
-      safe_yaml (~> 1.0.0)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    concurrent-ruby (1.1.5)
+    crack (0.4.4)
     diff-lcs (1.3)
     docile (1.3.1)
     gem_config (0.3.1)
-    hashdiff (0.3.7)
-    i18n (1.1.1)
+    hashdiff (1.0.1)
+    i18n (1.5.1)
       concurrent-ruby (~> 1.0)
     json (2.1.0)
     mime-types (3.2.2)
       mime-types-data (~> 3.2015)
-    mime-types-data (3.2018.0812)
-    minitest (5.11.3)
-    public_suffix (3.0.3)
+    mime-types-data (3.2019.0331)
+    minitest (5.13.0)
+    public_suffix (4.0.6)
     rake (12.3.1)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
@@ -45,7 +44,6 @@ GEM
       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)
       docile (~> 1.1)
       json (>= 1.8, < 3)
@@ -54,10 +52,10 @@ GEM
     thread_safe (0.3.6)
     tzinfo (1.2.5)
       thread_safe (~> 0.1)
-    webmock (2.3.2)
+    webmock (3.9.1)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
-      hashdiff
+      hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
   ruby
@@ -68,7 +66,7 @@ DEPENDENCIES
   rake (~> 12)
   rspec (~> 3.3)
   simplecov (~> 0)
-  webmock (~> 2)
+  webmock (~> 3)
 
 BUNDLED WITH
-   1.16.2
+   1.17.3

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 https://code.4me.com
+Copyright (c) 2019 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,17 +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
-* _max_retry_time_: maximum nr of seconds to wait for server to respond (default = 5400 = 1.5 hours)<br/>
+* _host_:           The [4me API host](https://developer.4me.com/v1/#service-url), default: 'https://api.4me.com'
+* _api_version_:    The [4me 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
+* _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/>
-  One retry will always be performed unless you set the value to -1.
+  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`
+* _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
@@ -68,7 +71,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]
 ```
@@ -82,7 +85,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:
 ```
@@ -103,8 +106,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:
 ```
@@ -121,7 +124,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
@@ -139,8 +142,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:
 ```
@@ -211,6 +214,14 @@ response = Sdk4me::Client.new.put('requests/416621', {
 })
 ```
 
+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.
 
@@ -233,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')
@@ -245,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
@@ -267,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))
@@ -279,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'
@@ -304,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.
+
+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 `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.
+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
 
@@ -319,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.
 

data/lib/sdk4me.rb

@@ -9,15 +9,16 @@ module Sdk4me
 
     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

data/lib/sdk4me/client.rb

@@ -27,7 +27,7 @@ module Sdk4me
     #
     # Shared configuration for all 4me SDK Clients:
     #   Sdk4me.configure do |config|
-    #     config.api_token = 'd41f5868feb65fc87fa2311a473a8766ea38bc40'
+    #     config.access_token = 'd41f5868feb65fc87fa2311a473a8766ea38bc40'
     #     config.account = 'my-sandbox'
     #     ...
     #   end
@@ -39,11 +39,11 @@ module Sdk4me
     #  - logger:      The Ruby Logger instance, default: Logger.new(STDOUT)
     #  - host:        The 4me API host, default: 'https://api.4me.com'
     #  - api_version: The 4me API version, default: 'v1'
-    #  - api_token:   *required* The 4me API token
+    #  - access_token: *required* The 4me access token
     #  - account:     Specify a different (trusted) account to work with
-    #                 @see http://developer.4me.com/v1/#multiple-accounts
+    #                 @see https://developer.4me.com/v1/#multiple-accounts
     #  - source:      The Source used when creating new records
-    #                 @see http://developer.4me.com/v1/general/source/
+    #                 @see https://developer.4me.com/v1/general/source/
     #
     #  - max_retry_time: maximum nr of seconds to wait for server to respond (default = 5400 = 1.5 hours)
     #                    the sleep time between retries starts at 2 seconds and doubles after each retry
@@ -51,7 +51,7 @@ module Sdk4me
     #                    one retry will always be performed unless you set the value to -1
     #  - read_timeout:   HTTP GET read timeout in seconds (default = 25)
     #  - block_at_rate_limit: Set to +true+ to block the request until the rate limit is lifted, default: +false+
-    #                         @see http://developer.4me.com/v1/#rate-limiting
+    #                         @see https://developer.4me.com/v1/#rate-limiting
     #
     #  - proxy_host:     Define in case HTTP traffic needs to go through a proxy
     #  - proxy_port:     Port of the proxy, defaults to 8080
@@ -59,12 +59,19 @@ module Sdk4me
     #  - proxy_password: Proxy password
     def initialize(options = {})
       @options = Sdk4me.configuration.current.merge(options)
-      [:host, :api_version, :api_token].each do |required_option|
+      [:host, :api_version].each do |required_option|
         raise ::Sdk4me::Exception.new("Missing required configuration option #{required_option}") if option(required_option).blank?
       end
+      @logger = @options[:logger]
       @ssl, @domain, @port = ssl_domain_port_path(option(:host))
+      unless option(:access_token).present?
+        if option(:api_token).blank?
+          raise ::Sdk4me::Exception.new("Missing required configuration option access_token")
+        else
+          @logger.info('Use of api_token is deprecated, consider switching to access_token instead.')
+        end
+      end
       @ssl_verify_none = options[:ssl_verify_none]
-      @logger = @options[:logger]
     end
 
     # Retrieve an option
@@ -211,7 +218,12 @@ module Sdk4me
     def expand_header(header = {})
       header = DEFAULT_HEADER.merge(header)
       header['X-4me-Account'] = option(:account) if option(:account)
-      header['AUTHORIZATION'] = 'Basic ' + ["#{option(:api_token)}:x"].pack('m*').gsub(/\s/, '')
+      if option(:access_token).present?
+        header['AUTHORIZATION'] = 'Bearer ' + option(:access_token)
+      else
+        token_and_password = option(:api_token).include?(':') ? option(:api_token) : "#{option(:api_token)}:x"
+        header['AUTHORIZATION'] = 'Basic ' + [token_and_password].pack('m*').gsub(/\s/, '')
+      end
       if option(:source)
         header['X-4me-Source'] = option(:source)
         header['HTTP_USER_AGENT'] = option(:source)
@@ -283,7 +295,7 @@ module Sdk4me
       elsif '303' == response.raw.code.to_s
         @logger.debug { "Redirect: #{response.raw.header['Location']}" }
       else
-        @logger.error { "Request failed: #{response.message}" }
+        @logger.error { "#{request.method} request to #{domain}:#{port}#{request.path} failed: #{response.message}" }
       end
       response
     end
@@ -298,14 +310,25 @@ module Sdk4me
   end
 
   module SendWithRateLimitBlock
-    # Wraps the _send method with retries when the server does not responsd, see +initialize+ option +:rate_limit_block+
+    # Wraps the _send method with retries when the server does not respond, see +initialize+ option +:rate_limit_block+
     def _send(request, domain = @domain, port = @port, ssl = @ssl)
-      return super(request, domain, port, ssl) unless option(:block_at_rate_limit)
-      now = Time.now
+      return super(request, domain, port, ssl) unless option(:block_at_rate_limit) && option(:max_throttle_time) > 0
+      now = nil
+      timed_out = false
       begin
         _response = super(request, domain, port, ssl)
-        @logger.warn { "Request throttled, trying again in 5 minutes: #{_response.message}" } and sleep(300) if _response.throttled?
-      end while _response.throttled? && (Time.now - now) < 3660 # max 1 hour and 1 minute
+        now ||= Time.now
+        if _response.throttled?
+          # if no Retry-After is not provided, the 4me server is very busy, wait 5 minutes
+          retry_after = _response.retry_after == 0 ? 300 : [_response.retry_after, 2].max
+          if (Time.now - now + retry_after) < option(:max_throttle_time)
+            @logger.warn { "Request throttled, trying again in #{retry_after} seconds: #{_response.message}" }
+            sleep(retry_after)
+          else
+            timed_out = true
+          end
+        end
+      end while _response.throttled? && !timed_out
       _response
     end
   end
@@ -314,15 +337,24 @@ module Sdk4me
   module SendWithRetries
     # Wraps the _send method with retries when the server does not respond, see +initialize+ option +:retries+
     def _send(request, domain = @domain, port = @port, ssl = @ssl)
+      return super(request, domain, port, ssl) unless option(:max_retry_time) > 0
       retries = 0
-      sleep_time = 2
-      total_retry_time = 0
+      sleep_time = 1
+      now = nil
+      timed_out = false
       begin
         _response = super(request, domain, port, ssl)
-        @logger.warn { "Request failed, retry ##{retries += 1} in #{sleep_time} seconds: #{_response.message}" } and sleep(sleep_time) if (_response.raw.code.to_s != '204' && _response.empty?) && option(:max_retry_time) > 0
-        total_retry_time += sleep_time
-        sleep_time *= 2
-      end while (_response.raw.code.to_s != '204' && _response.empty?) && total_retry_time < option(:max_retry_time)
+        now ||= Time.now
+        if _response.failure?
+          sleep_time *= 2
+          if (Time.now - now + sleep_time) < option(:max_retry_time)
+            @logger.warn { "Request failed, retry ##{retries += 1} in #{sleep_time} seconds: #{_response.message}" }
+            sleep(sleep_time)
+          else
+            timed_out = true
+          end
+        end
+      end while _response.failure? && !timed_out
       _response
     end
   end

data/lib/sdk4me/client/attachments.rb

@@ -8,21 +8,64 @@ module Sdk4me
       @client = client
     end
 
-    # upload the attachments in :attachments to 4me and return the data with the uploaded attachment info
+    # upload the attachments and return the data with the uploaded attachment info
+    # Two flavours available
+    #  * data[:attachments]
+    #  * data[:note] containing text with '[attachment:/tmp/images/green_fuzz.jpg]'
     def upload_attachments!(path, data)
-      raise_exceptions = !!data.delete(:attachments_exception)
+      upload_options = {
+        raise_exceptions: !!data.delete(:attachments_exception),
+        attachments_field: attachments_field(path),
+      }
+      uploaded_attachments = upload_normal_attachments!(path, data, upload_options)
+      uploaded_attachments += upload_inline_attachments!(path, data, upload_options)
+      # jsonify the attachments, if any were uploaded
+      data[upload_options[:attachments_field]] = uploaded_attachments.compact.to_json if uploaded_attachments.compact.any?
+    end
+
+    private
+
+    # upload the attachments in :attachments to 4me and return the data with the uploaded attachment info
+    def upload_normal_attachments!(path, data, upload_options)
       attachments = [data.delete(:attachments)].flatten.compact
-      return if attachments.empty?
+      return [] if attachments.empty?
 
-      # retrieve the upload configuration for this record from 4me
-      storage = @client.get(path =~ /\d+$/ ? path : "#{path}/new", {attachment_upload_token: true}, @client.send(:expand_header))[:storage_upload]
-      report_error("Attachments not allowed for #{path}", raise_exceptions) and return unless storage
+      upload_options[:storage] ||= storage(path, upload_options[:raise_exceptions])
+      return [] unless upload_options[:storage]
 
-      # upload each attachment and store the {key, filesize} has in the note_attachments parameter
-      data[attachments_field(path)] = attachments.map {|attachment| upload_attachment(storage, attachment, raise_exceptions) }.compact.to_json
+      attachments.map do |attachment|
+        upload_attachment(upload_options[:storage], attachment, upload_options[:raise_exceptions])
+      end
     end
 
-    private
+    INLINE_ATTACHMENT_REGEXP = /\[attachment:([^\]]+)\]/.freeze
+    # upload any '[attachment:/tmp/images/green_fuzz.jpg]' in :note text field to 4me as inline attachment and add the s3 key to the text
+    def upload_inline_attachments!(path, data, upload_options)
+      text_field = upload_options[:attachments_field].to_s.gsub('_attachments', '').to_sym
+      return [] unless (data[text_field] || '') =~ INLINE_ATTACHMENT_REGEXP
+
+      upload_options[:storage] ||= storage(path, upload_options[:raise_exceptions])
+      return [] unless upload_options[:storage]
+
+      attachments = []
+      data[text_field] = data[text_field].gsub(INLINE_ATTACHMENT_REGEXP) do |full_match|
+        attachment_details = upload_attachment(upload_options[:storage], $~[1], upload_options[:raise_exceptions])
+        if attachment_details
+          attachments << attachment_details.merge(inline: true)
+          "![](#{attachment_details[:key]})" # magic markdown for inline attachments
+        else
+          full_match
+        end
+      end
+      attachments
+    end
+
+    def storage(path, raise_exceptions)
+      # retrieve the upload configuration for this record from 4me
+      storage = @client.get(path =~ /\d+$/ ? path : "#{path}/new", {attachment_upload_token: true}, @client.send(:expand_header))[:storage_upload]
+      report_error("Attachments not allowed for #{path}", raise_exceptions) unless storage
+      storage
+    end
 
     def attachments_field(path)
       case path