crystal_sdk 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1dea48c45c081f3af807b9d3d23f1c67cbc6419b
-  data.tar.gz: 4b7c406415da2322c4c11200f2e4fb68389e2754
+  metadata.gz: 6ba27b0a6417d08fd9880ceebb13a9c948687a1c
+  data.tar.gz: 319692fbacdf2346768bac7820da9b4f5f4eeb4a
 SHA512:
-  metadata.gz: 9ec2f1e41105835b55dd790e543bb9ba5066f4c57a1faf0817bd578e55884041fc09a51892c61d48b64d0721c10497e56648600a1546a8616171572bc5d0c4c0
-  data.tar.gz: 99acff4789f52394971b2e0e9a585c76755fa6de6fae8991611a7431ecfa5e9e5ef174ba03d4a1c6099cab9cfa37bc8578cc6b47a7008067e5b8f420594ff4d0
+  metadata.gz: c9e85319e38fcbf762b87eecee617ae03a0adf3bb2a241292e24abc90a98fa052cc759165219a64d641ef78ac1f4a0ecff67acda949c36b0d565cfe8bc487e5f
+  data.tar.gz: b801219d333da34f0bc7425d456d781d027295f8d49ce7e875c902809d888a96eb718d7de0547d491e9af4222201cd03daadd558fba6f84d07b16ccb53c89fba

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    crystal_sdk (1.0.1)
+    crystal_sdk (1.0.2)
       nestful (~> 1.1)
       recursive-open-struct (~> 1.0)
 

data/README.md

@@ -2,6 +2,8 @@
 
 This gem provides access to Crystal, the world's largest and most accurate personality database!
 
+![Recommendations Demo](docs/recommendations.png)
+
 Here's how to install it:
 ```bash
 $ gem install crystal_sdk
@@ -9,6 +11,8 @@ $ gem install crystal_sdk
 
 Here's how you use it:
 
+## Synchronous Flow (Recommended)
+
 ```ruby
 require 'crystal_sdk'
 
@@ -34,13 +38,13 @@ begin
 
   print "Recommendations: #{profile.recommendations}"
 
-rescue CrystalSDK::Profile::NotFoundError => e
+rescue CrystalSDK::Profile::NotFoundError
   print "No profile was found"
 
 rescue CrystalSDK::Profile::NotFoundYetError => e
   print "Profile search exceeded time limit: #{e.request.id}"
 
-rescue CrystalSDK::Profile::RateLimitHitError => e
+rescue CrystalSDK::Profile::RateLimitHitError
   print "The organization's API rate limit was hit"
 
 rescue CrystalSDK::Profile::NotAuthedError => e
@@ -51,3 +55,95 @@ rescue StandardError => e
 
 end
 ```
+
+## Asynchronous Flow (For bulk analysis)
+
+When requesting large amounts of profiles, or when wanting to have more fine-grained control over performance, we recommend using our asynchronous flow. It allows us to process your requests in parallel and get the information back to you more quickly. There are a couple options for using this capability.
+
+### Option 1: Polling (Small Lists + Realtime Enrichment)
+The option we use internally in the SDK, is to poll for request information periodically until a set timeout has been reached:
+
+```ruby
+MAX_RETRIES = 10
+PAUSE_IN_SECONDS = 3
+
+# Start the request
+query = { first_name: "Drew", ... }
+request = CrystalSDK::Profile::Request.from_search(query)
+
+# Poll server until request finishes
+MAX_RETRIES.times do
+  
+  # If the request hasn't finished, wait and loop again
+  unless request.did_finish?
+    sleep(PAUSE_IN_SECONDS)
+    next
+  end
+
+  # Get profile information
+  if request.did_find_profile?
+    profile = Profile.from_request(request)
+  end
+  
+  break
+end
+
+# Use the profile if it was found
+profile
+```
+
+Polling can be extended to poll for multiple profiles. It gives the efficiency of our parallel processing, while writing code that behaves synchronously.
+
+This option is great if you want information as fast as possible while keeping open network connections and code complexity to a minimum. It is especially useful if you are requesting multiple profiles and can process the profiles one at a time, as each individual profile comes in (as opposed to waiting for all of them to come in before processing anything).
+
+
+### Option 2: Background Processing (Large Lists + Passive Enrichment)
+
+Sometimes, it isn't important to have the profile information immediately. Especially when dealing with larger jobs or passive data enrichment. In that case, we allow you to save the Request ID and pull information from the request at a later time via this ID.
+
+```ruby
+
+# Send the request to Crystal
+profile_request = CrystalSDK::Profile::Request.from_search(query)
+
+# Pull out the Profile Request ID (string)
+profile_request_id = profile_request.id
+
+# Save the Request ID somewhere (to a database or background job, for example)
+...
+
+# Later, pull up the Request ID and pull information about it
+backgrounded_request = CrystalSDK::Profile::Request.new(profile_request_id)
+
+if backgrounded_request.did_finish? && backgrounded_request.did_find_profile?
+  profile = backgrounded_request.profile
+  ...
+end
+```
+
+We try and store your request for a few days after the request has been started. Your Request ID should work when you try to pull information from it for at least that period of time!
+
+
+## Contributing
+
+- Clone the repository:
+
+  `git clone git@github.com:crystal-project-inc/ruby_sdk.git`
+
+- Run rspec tests:
+
+  `rspec`
+
+- Open up an IRB console with the gem loaded to play around with it:
+
+  `rake console`
+
+- Make a code change
+
+- Check that the tests still pass
+
+- Make a pull request!
+
+We will review the Pull Request to make sure that it does not break the external specification of the gem and that it fits with the overall mission of the SDK!
+
+We also encourage people to build further libraries that utilize our SDK and extend the use of the Connect API!

data/lib/crystal_sdk/profile.rb

@@ -21,21 +21,23 @@ module CrystalSDK
 
       def search(query, timeout: 30)
         request = nil
+        profile = nil
 
-        begin
-          Timeout.timeout(timeout) do
-            request = Profile::Request.from_search(query)
+        Timeout.timeout(timeout) do
+          request = Profile::Request.from_search(query)
 
-            loop do
-              sleep(2) && next unless request.did_finish?
+          loop do
+            sleep(2) && next unless request.did_finish?
+            raise NotFoundError unless request.did_find_profile?
 
-              raise NotFoundError unless request.did_find_profile?
-              return Profile.from_request(request)
-            end
+            profile = Profile.from_request(request)
+            break
           end
-        rescue Timeout::Error
-          raise NotFoundYetError.new(request)
         end
+
+        profile
+      rescue Timeout::Error
+        raise NotFoundYetError.new(request)
       end
     end
   end

data/lib/crystal_sdk/profile/request.rb

@@ -56,6 +56,10 @@ module CrystalSDK
       def did_finish?
         status = fetch_status
         status == 'complete' || status == 'error'
+      rescue Profile::NotFoundError
+        true
+      rescue Profile::NotAuthedError
+        true
       end
 
       def did_find_profile?
@@ -63,6 +67,8 @@ module CrystalSDK
 
         info = fetch_request_info
         !info[:data][:info][:error]
+      rescue Profile::NotFoundError
+        false
       end
 
       def profile_info

data/lib/crystal_sdk/version.rb

@@ -1,3 +1,3 @@
 module CrystalSDK
-  VERSION = '1.0.2'.freeze
+  VERSION = '1.0.3'.freeze
 end

data/spec/crystal_sdk/profile/request_spec.rb

@@ -156,6 +156,35 @@ describe CrystalSDK::Profile::Request do
       it { is_expected.to eql(true) }
     end
 
+    context '#fetch_status raises NotFoundError' do
+      before(:each) do
+        allow(request).to receive(:fetch_status)
+          .and_raise(CrystalSDK::Profile::NotFoundError)
+      end
+
+      it { is_expected.to eql(true) }
+    end
+
+    context '#fetch_status raises NotAuthedError' do
+      before(:each) do
+        allow(request).to receive(:fetch_status)
+          .and_raise(CrystalSDK::Profile::NotAuthedError.new('SomeToken'))
+      end
+
+      it { is_expected.to eql(true) }
+    end
+
+    context '#fetch_status raises an unexpected error' do
+      before(:each) do
+        allow(request).to receive(:fetch_status)
+          .and_raise('SomeError')
+      end
+
+      it 'should not suppress it' do
+        expect { subject }.to raise_error('SomeError')
+      end
+    end
+
     context '#fetch_status returns something else' do
       before(:each) do
         allow(request).to receive(:fetch_status).and_return('something')
@@ -177,6 +206,26 @@ describe CrystalSDK::Profile::Request do
       end
     end
 
+    context '#fetch_request_info raises NotFoundError' do
+      before(:each) do
+        allow(request).to receive(:fetch_request_info)
+          .and_raise(CrystalSDK::Profile::NotFoundError)
+      end
+
+      it { is_expected.to eql(false) }
+    end
+
+    context '#fetch_request_info raises unexpected error' do
+      before(:each) do
+        allow(request).to receive(:fetch_request_info)
+          .and_raise(CrystalSDK::Profile::NotAuthedError.new('SomeToken'))
+      end
+
+      it 'should not suppress it' do
+        expect { subject }.to raise_error(CrystalSDK::Profile::NotAuthedError)
+      end
+    end
+
     context '#did_finish? is true' do
       before(:each) do
         allow(request).to receive(:did_finish?).and_return(true)

data/spec/crystal_sdk/profile_spec.rb

@@ -43,11 +43,11 @@ describe CrystalSDK::Profile do
           .and_return(req)
 
         allow(req).to receive(:did_finish?)
-          .and_raise(StandardError.new)
+          .and_raise('SomeError')
       end
 
       it 'should raise exception' do
-        expect { subject }.to raise_error
+        expect { subject }.to raise_error('SomeError')
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: crystal_sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Cory Finger
@@ -82,6 +82,7 @@ files:
 - README.md
 - Rakefile
 - crystal_sdk.gemspec
+- docs/recommendations.png
 - lib/crystal_sdk.rb
 - lib/crystal_sdk/api.rb
 - lib/crystal_sdk/base.rb