promoted-ruby-client 0.1.0 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4494d298c8907ddb04588f1430d93ff2e83dd1978df0cfcb419df63db0cf302a
-  data.tar.gz: ab8105ad6c2dc8c8fc6992f5a312b240dcda3f13624fa3258fc769685ba9bdf3
+  metadata.gz: 6638e3f3f180e08d693f00d9d53caae30cfc737b2023adf0d181c18c1e379369
+  data.tar.gz: 429c6c2cfc5022ea9f38913cbc0e4b7d218787f817152661f2624d8265fd1f8b
 SHA512:
-  metadata.gz: 97a95326b32122f9d81292881c139cd0902f98c92dded7015d8ab7483c83b322f1e668f999da981a59e7c686523c74bf2ece6443e3dab26307cf44470f6a0cb9
-  data.tar.gz: 703316787c03c1e30eec766fda2f2247d357b8ad4e8c9b99765421a7d0fc119f998ba2cbb342044e229ad8067672a174a2f31f8cf62ce9206f545ba005fc1a11
+  metadata.gz: 9e9e040d1c232767af0004c92c7b3a79277b7ac0e5a3c45509c46bf869a6a51ed7b5ad4273c68c03c86833482607a2b63da8c43f819f73e069ca6a3caf24ddd3
+  data.tar.gz: 973bbfd858e00e5f81a42f221c5d2a90c8c2fb3bec93e5b1d8f38ca58c42c47382aa4ed777852ec3bee51483ff211b5da9041a075e285b738107be5f8c08567d

data/.gitignore

@@ -55,3 +55,6 @@ build-iPhoneSimulator/
 
 # Used by RuboCop. Remote config files pulled in from inherit_from directive.
 # .rubocop-https?--*
+
+# IDE
+.vscode/

data/Gemfile

@@ -6,4 +6,15 @@ git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 gemspec
 
 gem 'faraday', '~> 1.4.1'
-gem 'byebug'
+gem 'faraday_middleware'
+gem 'faraday-net_http'
+gem 'concurrent-ruby', require: 'concurrent'
+
+group :development do
+    gem 'ruby-debug-ide', group: :development
+    gem 'debase', '>= 0.2.5.beta2', group: :development
+    gem 'jaro_winkler', group: :development
+    gem 'solargraph', group: :development
+end
+
+gem 'simplecov', require: false, group: :test

data/Gemfile.lock

@@ -1,24 +1,56 @@
 PATH
   remote: .
   specs:
-    promoted-ruby-client (0.1.0)
+    promoted-ruby-client (0.1.5)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    byebug (11.1.3)
+    ast (2.4.2)
+    backport (1.2.0)
+    benchmark (0.1.1)
+    concurrent-ruby (1.1.9)
+    debase (0.2.5.beta2)
+      debase-ruby_core_source (>= 0.10.12)
+    debase-ruby_core_source (0.10.12)
     diff-lcs (1.4.4)
-    faraday (1.4.1)
+    docile (1.4.0)
+    e2mmap (0.1.0)
+    faraday (1.4.3)
+      faraday-em_http (~> 1.0)
+      faraday-em_synchrony (~> 1.0)
       faraday-excon (~> 1.1)
       faraday-net_http (~> 1.0)
       faraday-net_http_persistent (~> 1.1)
       multipart-post (>= 1.2, < 3)
       ruby2_keywords (>= 0.0.4)
+    faraday-em_http (1.0.0)
+    faraday-em_synchrony (1.0.0)
     faraday-excon (1.1.0)
     faraday-net_http (1.0.1)
     faraday-net_http_persistent (1.1.0)
+    faraday_middleware (1.0.0)
+      faraday (~> 1.0)
+    jaro_winkler (1.5.4)
+    kramdown (2.3.1)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    mini_portile2 (2.5.3)
     multipart-post (2.1.1)
+    nokogiri (1.11.7)
+      mini_portile2 (~> 2.5.0)
+      racc (~> 1.4)
+    parallel (1.20.1)
+    parser (3.0.1.1)
+      ast (~> 2.4.1)
+    racc (1.5.2)
+    rainbow (3.0.0)
     rake (10.5.0)
+    regexp_parser (2.1.1)
+    reverse_markdown (2.0.0)
+      nokogiri
+    rexml (3.2.5)
     rspec (3.10.0)
       rspec-core (~> 3.10.0)
       rspec-expectations (~> 3.10.0)
@@ -32,18 +64,64 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
     rspec-support (3.10.2)
+    rubocop (1.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.7.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.7.0)
+      parser (>= 3.0.1.1)
+    ruby-debug-ide (0.7.2)
+      rake (>= 0.8.1)
+    ruby-progressbar (1.11.0)
     ruby2_keywords (0.0.4)
+    simplecov (0.21.2)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.3)
+    solargraph (0.42.3)
+      backport (~> 1.2)
+      benchmark
+      bundler (>= 1.17.2)
+      diff-lcs (~> 1.4)
+      e2mmap
+      jaro_winkler (~> 1.5)
+      kramdown (~> 2.3)
+      kramdown-parser-gfm (~> 1.1)
+      parser (~> 3.0)
+      reverse_markdown (>= 1.0.5, < 3)
+      rubocop (>= 0.52)
+      thor (~> 1.0)
+      tilt (~> 2.0)
+      yard (~> 0.9, >= 0.9.24)
+    thor (1.1.0)
+    tilt (2.0.10)
+    unicode-display_width (2.0.0)
+    yard (0.9.26)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bundler (~> 1.17)
-  byebug
+  concurrent-ruby
+  debase (>= 0.2.5.beta2)
   faraday (~> 1.4.1)
+  faraday-net_http
+  faraday_middleware
+  jaro_winkler
   promoted-ruby-client!
   rake (~> 10.0)
   rspec (~> 3.0)
+  ruby-debug-ide
+  simplecov
+  solargraph
 
 BUNDLED WITH
-   1.17.2
+   1.17.3

data/README.md

@@ -2,45 +2,166 @@
 
 Ruby client designed for calling Promoted's Delivery and Metrics API.
 
-This version of the library only supports preparing objects for logging.  TODO - support Delivery API.
+More information at [http://www.promoted.ai](http://www.promoted.ai)
 
-## Expected pseudo-code flow for Metrics logging
+## Installation
+```gem 'promoted-ruby-client'```
 
-This example is for the integration where we do not want to modify the list of items to include `insertionId`.  TODO - add this example too.
+## Local Development
+1. Clone or fork the repo on your local machine
+2. `cd promoted-ruby-client`
+3. `bundle`
+4. To test interactively: `irb -Ilib -rpromoted/ruby/client`
 
+## Dependencies
+
+### [Faraday](https://github.com/lostisland/faraday)
+HTTP client for calling Promoted.
+### [Concurrent Ruby](https://github.com/ruby-concurrency/concurrent-ruby)
+Provides a thread pool for making shadow traffic requests to Delivery API in the background on a subset of calls to ```prepare_for_logging```
+## Creating a Client
+```rb
+client = Promoted::Ruby::Client::PromotedClient.new
 ```
-def get_items args
-  items = retrieve_items((args))
-  async_log_request(items)
-  return items
-end
 
-# Done async
-def log_request items
-  log_request = Promoted::Ruby::Client.prepare_for_logging(input)
-  # Send JSON to Metrics API.
-  log_to_promoted_event_api(log_request)
-end
+This client will suffice for building log requests. To send actually send traffing to the API, some configuration is required.
+
+```rb
+client = Promoted::Ruby::Client::PromotedClient.new({
+  :metrics_endpoint = "https://<get this from Promoted>",
+  :delivery_endpoint = "https://<get this from Promoted>",
+  :metrics_api_key = "<get this from Promoted>",
+  :delivery_api_key = "<get this from Promoted>"
+})
 ```
 
-## Naming details
+### Client Configuration Parameters
+Name | Type | Description
+---- | ---- | -----------
+```:delivery_endpoint``` | String | POST URL for the Promoted Delivery API (get this from Promoted)
+```:metrics_endpoint``` | String | POST URL for the Promoted Metrics API (get this from Promoted)
+```:metrics_api_key``` | String | Used as the ```x-api-key``` header on Metrics API requests to Promoted (get this value from Promoted)
+```:delivery_api_key``` | String | Used as the ```x-api-key``` header on Delivery API requests to Promoted (get this value from Promoted)
+```:delivery_timeout_millis``` | Number | Timeout on the Delivery API call. Defaults to 3000.
+```:metrics_timeout_millis``` | Number | Timeout on the Metrics API call. Defaults to 3000.
+```:perform_checks``` | Boolean | Whether or not to perform detailed input validation, defaults to true but may be disabled for performance
+```:logger``` | Ruby Logger-compatible logger | Defaults to nil (no logging). Example: ```Logger.new(STDERR, :progname => 'promotedai')```
+```:shadow_traffic_delivery_percent``` | Number between 0 and 1 | % of ```prepare_for_logging``` traffic that gets directed to Delivery API as "shadow traffic". Defaults to 0 (no shadow traffic).
+```:default_request_headers``` | Hash | Additional headers to send on the request beyond ```x-api-key```. Defaults to {}
+```:default_only_log``` | Boolean | If true, the ```deliver``` method will not direct traffic to Delivery API but rather return a request suitable for logging. Defaults to false.
+```:should_apply_treatment_func``` | Proc | Called during delivery, accepts an experiment and returns a Boolean indicating whether the request should be considered part of the control group (false) or in the experiment (true). If nil, the default behavior of checking the experiement ```:arm``` is applied.
+
+## Data Types
 
-`fullInsertion` - for `prepare_for_logging`, this is the current page of `Insertion`s with full `Insertion.properties` filled with the item details.  For v1 integrations, it is fine to not fill in the full properties.
+### UserInfo
+Basic information about the request user.
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:user_id``` | String | Yes | The platform user id, cleared from Promoted logs.
+```:log_user_id``` | String | Yes | A different user id (presumably a UUID) disconnected from the platform user id, good for working with unauthenticated users or implementing right-to-be-forgotten.
 
-## Pagination
+---
+### CohortMembership
+Useful fields for experimentation during the delivery phase.
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:user_info``` | UserInfo | Yes | The user info structure.
+```:arm``` | String | Yes | 'CONTROL' or one of the TREATMENT values (see [constants.rb](https://github.com/promotedai/promoted-ruby-client/blob/main/lib/promoted/ruby/client/constants.rb)).
+---
+### Properties
+Properties bag. Has the structure:
 
-The `prepare_for_logging` call assumes the client has already handled pagination.  It needs a `Request.paging.from` to be passed in for the number of items deep that the page is.
+```rb
+  :struct => {
+    :product => {
+      "id": "product3",
+      "title": "Product 3",
+      "url": "www.mymarket.com/p/3"
+      # other key-value pairs...
+    }
+  }
+```
+---
+### Insertion
+Content being served at a certain position.
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:user_info``` | UserInfo | Yes | The user info structure.
+```:insertion_id``` | String | Yes | Generated by the SDK (*do not set*)
+```:request_id``` | String | Yes | Generated by the SDK (*do not set*)
+```:content_id``` | String | No | Identifier for the content to be shown, must be set.
+```:properties``` | Properties | Yes | Any additional custom properties to associate. For v1 integrations, it is fine not to fill in all the properties.
 
-## Example to run the client
+---
+### Paging
+#### TODO
+---
+### Request
+A request for content insertions.
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:user_info``` | UserInfo | Yes | The user info structure.
+```:request_id``` | String | Yes | Generated by the SDK (*do not set*)
+```:use_case``` | String | Yes | One of the use case values, i.e. 'FEED' (see [constants.rb](https://github.com/promotedai/promoted-ruby-client/blob/main/lib/promoted/ruby/client/constants.rb)).
+```:properties``` | Properties | Yes | Any additional custom properties to associate.
+```:paging``` | Paging | Yes | Paging parameters (see TODO)
+---
+### MetricsRequest
+Input to ```prepare_for_logging```
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:request``` | Request | No | The underlying request for content.
+```:full_insertion``` | [] of Insertion | No | The proposed list of insertions.
+---
 
-1. Clone the repo on your local machine
-2. `cd promoted-ruby-client`
-3. `bundle`
-4. `irb -Ilib -rpromoted/ruby/client`
+### DeliveryRequest
+Input to ```deliver```
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:experiment``` | CohortMembership | Yes | A cohort to evaluation in experimentation.
+```:request``` | Request | No | The underlying request for content.
+```:full_insertion``` | [] of Insertion | No | The proposed list of insertions with all metadata, will be compacted before forwarding to Promoted.
+```:only_log``` | Boolean | Yes | Defaults to false. Set to true to override whether Delivery API is called for this request.
+---
 
-A console will launch with the library loaded.  Here is example code to use.
+### LogRequest
+
+Output of ```prepare_for_logging``` as well as an ouput of an SDK call to ```deliver```, input to ```send_log_request``` to log to Promoted
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:request``` | Request | No | The underlying request for content to log.
+```:insertion``` | [] of Insertion | No | The insertions, which are either the original request insertions or the insertions resulting from a call to ```deliver``` if such call occurred.
+---
+
+### ClientResponse
+Output of ```deliver```, includes the insertions as well as a suitable ```LogRequest``` for forwarding to Metrics API.
+Field Name | Type | Optional? | Description
+---------- | ---- | --------- | -----------
+```:insertion``` | [] of Insertion | No | The insertions, which are from Delivery API (when ```deliver``` was called, i.e. we weren't either only-log or part of an experiment) or the input insertions (when the other conditions don't hold).
+```:log_request``` | LogRequest | Yes | A message suitable for logging to Metrics API via ```send_log_request```. If the call to ```deliver``` was made (i.e. the request was not part of the CONTROL arm of an experiment or marked to only log), ```:log_request``` will not be set, as you can assume logging was performed on the server-side by Promoted.
+---
+
+### PromotedClient
+Method | Input | Output | Description
+------ | ----- | ------ | -----------
+```prepare_for_logging``` | MetricsRequest | LogRequest | Builds a request suitable for logging locally and/or to Promoted, either via a subsequent call to ```send_log_request``` in the SDK client or by using this structure to make the call yourself. Optionally, based on client configuration may send a random subset of requests to Delivery API as shadow traffic for integration purposes.
+```send_log_request``` | LogRequest | n/a | Forwards a LogRequest to Promoted using an HTTP client.
+```deliver``` | DeliveryRequest | ClientResponse | Makes a request (subject to experimentation) to Delivery API for insertions, which are then returned along with a LogRequest.
+```close``` | n/a | n/a | Closes down the client at shutdown, currently this is just to drain the thread pool that handles shadow traffic.
+---
+
+## Metrics API
+### Pagination
+
+The `prepare_for_logging` call assumes the client has already handled pagination.  It needs a `Request.paging.offset` to be passed in for the number of items deep that the page is.
+TODO: Needs more details.
+
+### Expected flow for Metrics logging
+
+```rb
+# Retrieve a list of content (i.e. products)
+# products = fetch_my_marketplace_products()
 
-```
 products = [
   {
     id: "123",
@@ -62,136 +183,91 @@ products = [
   }
 ]
 
-# Converts the Products to a list of Insertions.
-def to_insertions products
-  @to_insertions = []
-  products.each_with_index do |product, index|
-    @to_insertions << {
-      content_id: product[:id],
-      properties: {
-        struct: {
-          product: product.reject { |k, v| [:id].include? k }
-        }
+# Transform them into an [] of Insertions.
+insertions = products.map { |product| 
+  {
+    :content_id => product[:id],
+    :properties => {
+      :struct => {
+        :type => product[:type],
+        :name => product[:name]
+        # etc
       }
     }
-  end
-  @to_insertions
-end
+  }
+}
 
-request_input = {
-  request: {
-    user_info: { user_id: "912", log_user_id: "912191"},
-    use_case: "FEED",
-    paging: {
-      from: 10,
-      size: 5
+# Form a MetricsRequest
+metrics_request = {
+  :request => {
+    :user_info => { :user_id => "912", :log_user_id => "912191"},
+    :use_case => "FEED",
+    :paging => {
+      :offset => 0,
+      :size => 5
     },
-    properties: {
-      struct: {
-        active: true
+    :properties => {
+      :struct => {
+        :active => true
       }
     }
   },
-  fullInsertion: to_insertions(products)
+  :full_insertion => insertions
 }
 
-log_request = Promoted::Ruby::Client.prepare_for_logging(request_input)
-log_request.to_json
-```
+# OPTIONAL: You can pass a custom function to "compact" insertions before metrics logging.
+# Note that the PromotedClient has a class method helper, copy_and_remove_properties, that does just this.
+to_compact_metrics_insertion_func = Proc.new do |insertion|
+  insertion.delete(:properties)
+  insertion
+end
+# metrics_request[:to_compact_metrics_insertion_func] = to_compact_metrics_insertion
 
-`log_request.to_json` returns a result that looks like the following
-```
-=> "{\"user_info\":{\"user_id\":\"912\",\"log_user_id\":\"912191\"},\"timing\":{\"client_log_timestamp\":1623306198},\"request\":[{\"user_info\":{\"user_id\":\"912\",\"log_user_id\":\"912191\"},\"use_case\":\"FEED\",\"paging\":{\"from\":10,\"size\":10},\"properties\":{\"struct\":{\"active\":true}}}],\"insertion\":[{\"content_id\":\"123\",\"properties\":{\"struct\":{\"product\":{\"type\":\"SHOE\",\"name\":\"Blue shoe\",\"total_sales\":1000}}},\"user_info\":{\"user_id\":\"912\",\"log_user_id\":\"912191\"},\"timing\":{\"client_log_timestamp\":1623306198},\"insertion_id\":\"a87e1b57-a574-424f-8af6-10e0250aa7ab\",\"request_id\":\"54ff4884-2192-4180-8c72-a805a436980f\",\"position\":10},{\"content_id\":\"124\",\"properties\":{\"struct\":{\"product\":{\"type\":\"SHIRT\",\"name\":\"Green shirt\",\"total_sales\":800}}},\"user_info\":{\"user_id\":\"912\",\"log_user_id\":\"912191\"},\"timing\":{\"client_log_timestamp\":1623306198},\"insertion_id\":\"4495f72a-8101-4cb8-94ce-4db76839b8b6\",\"request_id\":\"54ff4884-2192-4180-8c72-a805a436980f\",\"position\":11},{\"content_id\":\"125\",\"properties\":{\"struct\":{\"product\":{\"type\":\"DRESS\",\"name\":\"Red dress\",\"total_sales\":1200}}},\"user_info\":{\"user_id\":\"912\",\"log_user_id\":\"912191\"},\"timing\":{\"client_log_timestamp\":1623306198},\"insertion_id\":\"d1e4f3f6-1783-4059-8fab-fdf2ba343cdf\",\"request_id\":\"54ff4884-2192-4180-8c72-a805a436980f\",\"position\":12}]}"
-```
+# Create a client
+client = Promoted::Ruby::Client::PromotedClient.new
 
-## Other input syntaxes
+# Build a log request
+log_request = client.prepare_for_logging(metrics_request)
 
-The client should also work if Hash rocket too.
+# Log (assuming you have configured your client with a :metrics_endpoint)
+client.send_log_request(log_request)
 ```
-products = [
-  {
-    "id"=>"123",
-    "type"=>"SHOE",
-    "name"=>"Blue shoe",
-    "totalSales"=>1000
-  },
-  {
-    "id"=>"124",
-    "type"=>"SHIRT",
-    "name"=>"Green shirt",
-    "totalSales"=>800
-  },
-  {
-    "id"=>"125",
-    "type"=>"DRESS",
-    "name"=>"Red dress",
-    "totalSales"=>1200
-  }
-]
 
-input = {
-  "request"=>{
-    "user_info"=>{"user_id"=> "912", "log_user_id"=> "912191"},
-    "use_case"=>"FEED",
-    "properties"=>{
-      "struct"=>{
-        "active"=>true
+## Delivery API
+
+### Expected flow for Delivery
+
+```rb
+# (continuing from the above example for Metrics)
+
+# Form a DeliveryRequest
+delivery_request = {
+  :request => {
+    :user_info => { :user_id => "912", :log_user_id => "912191"},
+    :use_case => "FEED",
+    :paging => {
+      :offset => 0,
+      :size => 5
+    },
+    :properties => {
+      :struct => {
+        :active => true
       }
     }
   },
-  "fullInsertion"=>to_insertions(products)
+  :full_insertion => insertions,
+  :only_log => false
 }
-```
 
-Or inlined full request.
+# Request insertions from Delivery API
+client_response = client.deliver(delivery_request)
+
+# Use the resulting insertions
+client_response[:insertion]
+
+# Log if a log request was provided (if not, deliver was called successfully
+# and Promoted logged on the server-side).)
+client.send_log_request(client_response[:log_request]) if client_response[:log_request]
 ```
-input = {
-  "request"=>{
-    "user_info"=>{"user_id"=> "912", "log_user_id"=> "912191"},
-    "use_case"=>"FEED",
-    "properties"=>{
-      "struct"=>{
-        "active"=>true
-      }
-    }
-  },
-  "fullInsertion"=>[
-    {
-      "contentId"=>"123",
-      "properties"=>{
-        "struct"=>{
-          "product"=>{
-            "type"=>"SHOE",
-            "name"=>"Blue shoe",
-            "totalSales"=>1000
-          }
-        }
-      }
-    },
-    {
-      "contentId"=>"124",
-      "properties"=>{
-        "struct"=>{
-          "product"=>{
-            "type"=>"SHIRT",
-            "name"=>"Green shirt",
-            "totalSales"=>800
-          }
-        }
-      }
-    },
-    {
-      "contentId"=>"125",
-      "properties"=>{
-        "struct"=>{
-          "product"=>{
-            "type"=>"DRESS",
-            "name"=>"Red dress",
-            "totalSales"=>1200
-          }
-        }
-      }
-    }
-  ]
-}
-```
+
+### TODO Experimentation example