preferredpictures 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab3bdaa1764dba2ea124cc5ebe941e8d2f347da5bf29e2a929d205b62fc4ffe3
-  data.tar.gz: 01562b758516fa8ea9fc4ed9a6096a4ba93c5216e17bf8aba72d224a68bbf630
+  metadata.gz: 7519f3ed012ccd405a556693e5a5f3d23cd7852b00d688616224907cfc7a0a0d
+  data.tar.gz: 81316ab2943a9f39223bbdfa8f6c6f82d7b01313e60d71c2e2af798ee06b8484
 SHA512:
-  metadata.gz: 4d04f7cc0e44f183e2a64ac18ae3cdece8305086fb2befd2bb64b57263732df0ed049830499deb40ecc46229c5bd1fbc5218b4024ed1b4d99d06c3713a2e8d65
-  data.tar.gz: e89cba6af7e6bdb1f13fbd860970783003d8196c4f4ae66a67111a50bc8e4f885b3ab9cbc689aecda9359f45ee2f6c28d7d20d9929739b3482aa941d3779b028
+  metadata.gz: 9aa226f4d0645c8fea3fbdd9d698d05594dd0f38fc39af75992b7ffaeb2b5dd25c85581eebf493cf443895178617bb8ab83967a3f4838fd7cf3b279b2c9bef0e
+  data.tar.gz: 5d6eff8a9e950763012e822b789b9aaf9b9183ad4d8d764a38cdbb74bdfb3f163374d243c25df055363a5183ce2790dceb0ca07af902e49d127890e32103825e

data/Gemfile

@@ -5,3 +5,5 @@ gemspec
 
 gem "rake", "~> 12.0"
 gem "rspec", "~> 3.0"
+
+gem "httparty", "~> 0.18.1"

data/README.md

@@ -1,7 +1,11 @@
-# Preferred.pictures Ruby Client Library
+# PreferredPictures Ruby Client Library
 
-The [Preferred.pictures](https://preferred.pictures) PHP library provides a convenient way to call the
-[Preferred.pictures](https://preferred.pictures) API for applications written in Ruby
+The [PreferredPictures](https://preferred.pictures) PHP library provides a convenient way to call the
+[PreferredPictures](https://preferred.pictures) API for applications written in Ruby
+
+[View the full documentation about the PreferredPicture's API](https://docs.preferred.pictures/api-sdks/api)
+
+[Learn more about what PreferredPictures can do.](https://docs.preferred.pictures/)
 
 ## Installation
 
@@ -20,31 +24,32 @@ Or install it yourself as:
 ## Usage
 
 ```ruby
+require "preferredpictures"
 
 # Create a new client using an issued identity
 # and a secret key
-client = PreferredPictures::Client.new("testidentity", "secret123456")
+client = PreferredPictures::Client.new(
+    identity: "testidentity",
+    secret_key: "secret123456")
 
 # A simple example with just choices and the a tournament.
 url = client.createChooseUrl(
-    ['https://example.com/image-red.jpg',
-    'https://example.com/image-green.jpg',
-    'https://example.com/image-blue.jpg'],
-    'test-tournament')
+    choices: ['https://example.com/image-red.jpg',
+              'https://example.com/image-green.jpg',
+              'https://example.com/image-blue.jpg'],
+    tournament: 'test-tournament')
 
-# A more involved example setting the ttl's and using
-# a prefix and suffix applied to the choices for brevity
+# A more involved example setting a prefix and suffix
+# applied to the choices for brevity
 url = client.createChooseUrl(
-    ['red', 'green', 'blue'],
-    'test-tournament',
-    600,
-    3600,
-    "https://example.com/image-",
-    ".jpg")
+    choices: ['red', 'green', 'blue'],
+    tournament: 'test-tournament',
+    choices_prefix: "https://example.com/image-",
+    choices_suffix: ".jpg")
 
 # The url returned will appear to be something like:
 #
-# https://api.preferred.pictures/choose-url?choices=red%2Cgreen%2Cblue&tournament=testing&expiration=[EXPIRATION]&uid=[UNIQUEID]&ttl=600&prefix=https%3A%2F%2Fexample.com%2Fjacket-&suffix=.jpg&identity=test-identity&signature=[SIGNATURE]
+# https://api.preferred-pictures.com/choose-url?choices=red%2Cgreen%2Cblue&tournament=testing&expiration=[EXPIRATION]&uid=[UNIQUEID]&ttl=600&prefix=https%3A%2F%2Fexample.com%2Fjacket-&suffix=.jpg&identity=test-identity&signature=[SIGNATURE]
 #
 # which should be placed where it is needed in your application or templates.
 ```

data/lib/preferredpictures.rb

@@ -2,68 +2,157 @@ require "preferredpictures/version"
 require 'securerandom'
 require 'openssl'
 
+##
+# The encompassing class for the PreferredPictures API
+#
 module PreferredPictures
+
+  ##
+  # A class representing an error from a PreferredPictures
+  # call
   class Error < StandardError; end
 
+  ##
+  # The client class of PreferredPictures
   class Client
 
-    # Initialize a new Preferred.pictures client which will be used to create
+    ##
+    # Initialize a new PreferredPictures client which will be used to create
     # and sign API requests
     #
-    # - identity: The Preferred.pictures identity that will be used.
-    # - secret_key: The secret key associated with the identity that is used to sign requests
-    # - max_choices: The maximum number of choices to allow
-    # - endpoint: The Preferred.pictures API endpoint to use.
+    # ==== Options
+    #
+    # * +:identity+ - (String) The PreferredPictures identity that will be used.
+    # * +:secret_key+ - (String) The secret key associated with the identity that is used to sign requests
+    # * +:max_choices+ - (Number) The maximum number of choices to allow
+    # * +:endpoint+ - (String) The PreferredPictures API endpoint to use for requests.
+    #
+    # ==== Examples
+    #
+    # This will create an example PreferredPictures client.
     #
-    def initialize(identity, secret_key, max_choices=35, endpoint="https://api.preferred.pictures/")
+    #    client = PreferredPictures::Client.new(identity: "testidentity",
+    #                                           secret_key: "secret123456")
+    #
+    def initialize(identity:, secret_key:, max_choices: 35, endpoint: "https://api.preferred-pictures.com/")
       @identity = identity
       @secret_key = secret_key
       @max_choices = max_choices
       @endpoint = endpoint
     end
 
-    # Return a URL that calls the Preferred.pictures API to choose one option
-    # among the supplied chocies.
+    ##
+    # Create a URL that calls the PreferredPictures API to
+    # choose one option among the supplied chocies.
+    #
+    # ==== Options
+    #
+    # * +:choices+ (Array<String>) A list of choices of which the API should choose
+    # * +:tournament+ (String) The tournament where this request will participate
+    # * +:ttl+ (Number) The time to live for an action to be taken from the choice, specified in seconds
+    # * +:expiration_ttl+ (Number) The time to live for the URL's signature, after this time the request
+    # *                 will no longer be valid.
+    # * +:uid+ (String) An optional unique identifier that will be used to correlate choices and
+    # *      actions
+    # * +:choices_prefix+ (String) An optional prefix to prepend to all of the choices.
+    # * +:choices_suffix+ (String) An optional suffix to append to all of the choices.
+    # * +:destinations+ (Array<String) An array of destination URLs that are paired with each of the choices
+    # * +:destinations_prefix+ (String) An optional prefix to prepend to all of the destination URLs
+    # * +:destinations_suffix+ (String) An optional suffix to append to all of the destination URLs
+    # * +:go+ (Boolean) Indicate that the result should be a redirect to a destination URL from
+    # *     a previously made choice
+    # * +:json+ (Boolean) Return the choice using JSON rather than a HTTP 302 redirect.
     #
-    # - choices: A list of choices of which the API should choose
-    # - tournament: The tournament where this request will participate
-    # - ttl: The time to live for an action to be taken from the choice, specified in seconds
-    # - expiration_ttl: The time to live for the URL's signature, after this time the request
-    #                   will no longer be valid.
-    # - prefix: An optional prefix to prepend to all of the choices.
-    # - suffix: An optional suffix to append to all of the choices.
+    # ==== Examples
     #
-    def createChooseUrl(choices, tournament, ttl=600, expiration_ttl=3600, prefix="", suffix="")
+    # This will create an PreferredPictures URL that will result in a choice:
+    #
+    #    client = PreferredPictures::Client.new(
+    #        identity: "testidentity",
+    #        secret_key: "secret123456")
+    #
+    #    url = client.createChooseUrl(
+    #        choices: ['a', 'b', 'c'],
+    #        tournament: 'test-ruby-tournment',
+    #        choices_prefix: "https://example.com/image-",
+    #        choices_suffix: ".jpg")
+    #
+    #
+    def createChooseUrl(choices:,
+                        tournament:,
+                        ttl: 600,
+                        expiration_ttl: 3600,
+                        uid: "",
+                        choices_prefix: "",
+                        choices_suffix: "",
+                        destinations: [],
+                        destinations_prefix: "",
+                        destinations_suffix: "",
+                        go: false,
+                        json: false)
 
       if choices.length() > @max_choices
         raise Error.new "Too many choices were supplied"
       end
 
+      if choices.length() === 0
+        raise Error.new "No choices were supplied"
+      end
+
       params = {
-        "choices" => choices.join(","),
+        "choices[]" => choices,
         # Set the expiration of the request to be an hour
         # from when it is generated.
         "expiration" => Time.now.to_i + expiration_ttl,
-        # The identifier of the tournamen
+        # The identifier of the tournament
         "tournament" => tournament,
-        # The unique id of this request
-        "uid" => SecureRandom.uuid,
         "ttl" => ttl,
       };
 
-      if prefix != ""
-        params['prefix'] = prefix
+      if uid == ""
+        params['uid'] = SecureRandom.uuid
+      else
+        params['uid'] = uid
+      end
+
+      if choices_prefix != ""
+        params['choices_prefix'] = choices_prefix
+      end
+
+      if choices_suffix != ""
+        params['choices_suffix'] = choices_suffix
+      end
+
+      if destinations_prefix != ""
+        params['destinations_prefix'] = destinations_prefix
+      end
+
+      if destinations_suffix != ""
+        params['destinations_suffix'] = destinations_suffix
       end
 
-      if suffix != ""
-        params['suffix'] = suffix
+      if destinations.length > 0
+        params['destinations[]'] = destinations
+      end
+
+      if go
+        params['go'] = 'true'
+      end
+
+      if json
+        params['json'] = 'true'
       end
 
       signing_field_order = [
-        "choices",
+        "choices_prefix",
+        "choices_suffix",
+        "choices[]",
+        "destinations_prefix",
+        "destinations_suffix",
+        "destinations[]",
         "expiration",
-        "prefix",
-        "suffix",
+        "go",
+        "json",
         "tournament",
         "ttl",
         "uid",
@@ -71,15 +160,16 @@ module PreferredPictures
 
       signing_string = signing_field_order
         .select { |field_name| params.has_key?(field_name) }
-        .map{|field_name| params[field_name]}
+        .map{ |field_name| params[field_name].kind_of?(Array) ? params[field_name].join(",") : params[field_name] }
         .join("/")
 
-
       sha256 = OpenSSL::Digest.new('sha256')
       signature = OpenSSL::HMAC.hexdigest(sha256, @secret_key, signing_string)
 
-      return @endpoint + "choose-uri?" + URI.encode_www_form(params)
-    end
+      params['signature'] = signature
+      params['identity'] = @identity
 
+      return @endpoint + "choose?" + URI.encode_www_form(params)
+    end
   end
 end

data/lib/preferredpictures/version.rb

@@ -1,3 +1,3 @@
 module PreferredPictures
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/preferredpictures.gemspec

@@ -6,13 +6,12 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Preferred Pictures"]
   spec.email         = ["contact@preferred.pictures"]
 
-  spec.summary       = %q{Preferred.pictures Ruby client library}
-  spec.description   = %q{The Preferred.pictures Ruby client library provides a convenient way to call the Preferred.pictures API for applications written in Ruby.}
+  spec.summary       = %q{PreferredPictures Ruby client library}
+  spec.description   = %q{The PreferredPictures Ruby client library provides a convenient way to call the PreferredPictures API for applications written in Ruby.}
   spec.homepage      = "https://github.com/preferred-pictures/ruby"
   spec.license       = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
 
-
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/preferred-pictures/ruby.git"
 
@@ -24,4 +23,6 @@ Gem::Specification.new do |spec|
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "rspec", "~> 3.2"
 end

metadata

@@ -1,17 +1,31 @@
 --- !ruby/object:Gem::Specification
 name: preferredpictures
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Preferred Pictures
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-07-16 00:00:00.000000000 Z
-dependencies: []
-description: The Preferred.pictures Ruby client library provides a convenient way
-  to call the Preferred.pictures API for applications written in Ruby.
+date: 2020-08-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+description: The PreferredPictures Ruby client library provides a convenient way to
+  call the PreferredPictures API for applications written in Ruby.
 email:
 - contact@preferred.pictures
 executables: []
@@ -55,5 +69,5 @@ requirements: []
 rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: Preferred.pictures Ruby client library
+summary: PreferredPictures Ruby client library
 test_files: []