projector 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b01c748ddaf5071ff777617069d58c659ad50939
-  data.tar.gz: 8b0bdcc7690ece29913b18a628cc79545322db8f
+  metadata.gz: e5207d8f41bed6a38021ab35f4593d04b30e3acc
+  data.tar.gz: b1c1928c82e355a58e2bb3c1b30b93dd4f0a45d5
 SHA512:
-  metadata.gz: 382ccef4f65a69c0b3653b6dacbfa1a3deebfcb08625ccba6fba8891d1fa593a5e4387f43c24b4a691c0d256c99932c4f083d56dfee75c1937f058b6754e5abf
-  data.tar.gz: 45ae036f1e0d756770ca7f3751d888a7a661e8d62b50f4d5728d643abced1d0c2b822dc628ab1ad504fd8234f29a85d5c950bc71b4cd0143c18223dddfab7fd3
+  metadata.gz: e498f9b613d6562a6fe07d39ce8d5070c58c3a762f687fddc431af3e87e709b1cd9c792977b1fda040b54b61dd0fda72fe020e353085202de78225f95c8c776f
+  data.tar.gz: 8568bd726be3187241a39508af57f23707a21d792ff758d1a7542295581c519825666ea90ec7ef6138090ee5dfee2f4060785fb0789035392140256f4f5b197a

data/.yardopts

@@ -0,0 +1 @@
+yardoc --protected ./lib/**/*.rb --readme Overview.md

data/Overview.md

@@ -0,0 +1,66 @@
+# Projector Ruby SDK
+
+## Installation
+Add the Projector Ruby SDK gem to your Gemfile with the following:
+
+```
+gem 'projector'
+```
+
+Install it by running the following using bundler:
+
+```
+bundle install
+```
+
+## Configuration
+See {Projector::Client} for information on configuring the client.
+
+## Interacting with the Projector API
+See {Projector::ApiMethods} for information on public API methods exposed in this SDK.
+
+## Handling Errors
+If an error occurs, an exception will be thrown which the user can catch and inspect for further details.
+
+The Projector SDK can encounter two types of errors when communicating with Projector's systems - Internal Server and Client Errors. All errors subclass from {Projector::Error}.
+
+### Client Errors
+The Projector SDK has two types of Client Errors - {Projector::Unauthorized} and {Projector::BadRequest}. Making a request with safeguards for both can be done as follows:
+
+```
+begin
+  Projector.register_end_user(end_user)
+rescue Projector::Unauthorized => auth_error
+  puts auth_error.response_body
+rescue Projector::BadRequest => bad_request_error
+  puts bad_request_error.response_body
+else
+  puts 'Unknown error'
+end
+```
+
+### Internal Server Errors
+These type of errors can happen for a number of reasons; our servers might be at capacity and we are in the process of scaling them up, a request might have hit an instance being removed from service or other intermittent failure. Making a request can be safeguarded from then as follows:
+
+```
+begin
+  Projector.register_end_user(end_user)
+rescue Projector::InternalServerError => server_error
+  if server_error.retry_after 
+    sleep server_error.retry_after
+  else
+    #Retry later
+  end
+end
+```
+
+You can retry repeatedly but if the error does not eventually clear up reach out to Projector and we will look into the issue with you. Please include the Request ID, also available as a property on the exception.
+
+```
+begin
+  Projector.register_end_user(end_user)
+rescue Projector::InternalServerError => server_error
+  # If the error does not recover, notify Projector including the Request Id
+  puts server_error.request_id 
+end
+```

data/README.md

@@ -1,6 +1,6 @@
 # Projector Ruby SDK
 
-[SDK Guide](https://goprojector.readme.io/docs/ruby-1)
+See [our SDK documentation](https://projectorhq.github.io/ruby-sdk/) and [getting started guide](https://docs.projector.com/v1.0/docs/ruby).
 
 ## Installation
 

data/Rakefile

@@ -21,7 +21,7 @@ task :default => :test
 
 desc "Publish SDK docs to GitHub Pages"
 task :publish_docs do
-  system("set -x; bundle exec yardoc --protected ./lib/**/*.rb ") or abort
+  system("set -x; bundle exec yardoc") or abort
   system("set -x; mv -v ./doc /tmp ") or abort
   system("set -x; git checkout gh-pages ") or abort
   system("set -x; cp -r /tmp/doc/* . ") or abort

data/lib/projector.rb

@@ -1,26 +1,35 @@
 require 'projector/version'
 require 'projector/client'
 
+# Main interface for interacting with the Projector SDK. This class forwards method calls to an
+# internal instance of {Projector::Client}, allowing you to make calls like {Projector::ApiMethods#deliver_event Projector.deliver_event(event)}
+# without explicitly constructing an instance. Instances constructed in this way will use the default
+# options specified using either {Projector::Client 12-factor environment variables} or via {Projector::Client.configure}.
+#
+# If you wish to keep a persistent {Projector::Client} instance for some reason, construct it using {Projector::Client#initialize new Projector::Client(options)}.
 module Projector
   class << self
     # Alias for Projector::Client.new
     #
+    # @param [Hash] options configuration options
     # @return [Projector::Client]
     def new(options = {})
       Projector::Client.new(options)
     end
 
-    # Delegate to Projector::Client.new
+    # Delegate to an instance of {Projector::Client}
     def method_missing(method, *args, &block)
       return super unless new.respond_to?(method)
       new.send(method, *args, &block)
     end
 
-    # Forward respond_to? to Projector::Client.new
+    # Forward respond_to? to an instance of {Projector::Client}.
     def respond_to?(method, include_private = false)
       new.respond_to?(method, include_private) || super(method, include_private)
     end
 
+    # The Logger instance for internal logging. Defaults to the Rails logger or STDOUT.
+    # @return [Logger]
     def logger
       @logger ||= begin
                     if defined?(::Rails)
@@ -32,26 +41,9 @@ module Projector
                   end
     end
 
+    # Sets the logger instance for the Projector SDK
     def logger=(x)
       @logger = x
     end
-
-    DEFAULT_ERROR_HANDLER = Proc.new do |ex, ctx|
-      Projector.logger.error(ex)
-      Projector.logger.error(ctx.inspect)
-      ex.backtrace.each do |line|
-        Projector.logger.error(line)
-      end if ex.backtrace
-    end
-
-    ##
-    # Add a global error handler for any async errors Projector encounters.
-    # Error handlers must respond to `call(exception, context_hash)`:
-    #
-    #     Projector.error_handlers << Proc.new {|ex, ctx| do_something(ex) }
-    #
-    def error_handlers
-      @handlers ||= [DEFAULT_ERROR_HANDLER]
-    end
   end
 end

data/lib/projector/api_methods.rb

@@ -1,5 +1,21 @@
 module Projector
+  # Ruby method wrappers for the Projector API. 
   module ApiMethods
+
+    # Registers or updates an end user at Projector
+    #
+    # @param [Hash] end_user a hash of the end user object
+    # @option end_user [String] :id the ID of the user in your application
+    # @option end_user [Array] :tags an array of tags to apply to the user
+    # @return [Hash] a hash of data that should be returned as part of the registration API call
+    # @example Register an end user
+    #   end_user = {
+    #    id: '42',
+    #    tags: ['likes_dogs']
+    #   }
+    #   Projector.register_end_user(end_user)
+    # @raise {Projector::Unauthorized}
+    # @raise {Projector::BadRequest}
     def register_end_user(end_user)
       # If a hash is passed, use it to populate a user object
       if end_user.instance_of?(Hash)
@@ -9,14 +25,52 @@ module Projector
         user = end_user
       end
       # return the data element of the resulting envelope
-      post(host, '/end_users', Projector::Envelope.new(Projector::EndUser::SCHEMA, user).to_hash).body
+      post(host, '/end_users', Projector::Envelope.new(user).to_hash).body
     end
 
+    # Updates tags on an end user at Projector
+    #
+    # @param [String] id the ID of the user in your application
+    # @param [Array] tags an array of tags to apply to the user
+    # @example Update a user's tags
+    #   Projector.set_end_user_tags('51', ['likes_dogs', 'has_dog'])
+    # @raise {Projector::Unauthorized}
+    # @raise {Projector::BadRequest}
+    # @return [Hash]
     def set_end_user_tags(id, tags)
       user = Projector::EndUser.new(id: id, tags: tags)
       register_end_user(user)
     end
 
+    # Sends an event to one or more users at Projector
+    #
+    # @param [Hash] event a hash of the event object
+    # @option event [String] :id (SecureRandom.uuid) the ID the event
+    # @option event [String] :event_key the event key for this type of event
+    # @option event [String] :event_time (Time.now) the event time in ms from epoch for this event
+    # @option event [Hash] :target the recipient or recipients of the event
+    # @option event [Hash] :event_context data for use in delivery rules and notification alert templates at Projector
+    # @option event [Hash] :payload JSON data properties to be delivered on the event (deep links, metadata, etc)
+    # @example Sending a notification to one or more individual users
+    #   event = {
+    #     id: 'like-event-7391',
+    #     event_key: 'liked-your-dog',
+    #     event_context: {dog_name: 'Barclay', liker_name: 'Jana', liker_id: '42'},
+    #     target: {end_users: [{id: '51'}]}    
+    #   }
+    #   Projector.deliver_event(event)
+    # @example Sending a notification to one or more tags
+    #   event = {
+    #     id: 'new-dog-492',
+    #     event_key: 'new-dog',
+    #     event_context: {dog_name: 'Pixel', color: 'blond', size: 'small'},
+    #     target: {tags: ['likes_dogs']}    
+    #   }
+    #   Projector.deliver_event(event)
+    # @raise {Projector::InvalidEvent}
+    # @raise {Projector::Unauthorized}
+    # @raise {Projector::BadRequest}
+    # @return [Hash]
     def deliver_event(event)
       # Create an Event instance if the parameter is a Hash.
       if event.instance_of?(Hash)
@@ -24,7 +78,7 @@ module Projector
       end
       # Verify that we've got an Event object.
       raise Projector::InvalidEvent.new("Invalid event data") unless event.instance_of?(Projector::Event)
-      post(host, '/events', Projector::Envelope.new(Projector::Event::SCHEMA, event).to_hash).body
+      post(host, '/events', Projector::Envelope.new(event).to_hash).body
     end
   end
 end

data/lib/projector/client.rb

@@ -1,4 +1,4 @@
- module Projector
+module Projector
   require 'projector/transport/http'
   require 'projector/error'
   require 'projector/envelope'
@@ -6,11 +6,26 @@
   require 'projector/event'
   require 'projector/api_methods'
 
+  # Primary static class for interacting with the Projector API.
+  #
+  # The Projector SDK accepts direct configuration or uses environment variables, in support of the 
+  # {http://12factor.net/ Twelve Factor Application} pattern. PROJECTOR_API_HOST and PROJECTOR_API_TOKEN
+  # variables are used by default. 
+  #
+  # If you wish to manually configure the client, create an initializer and use the {Projector::Client.configure} 
+  # block to set properties as needed.
+  #
+  # @example Manually configuring the Proejctor Client
+  #   require 'projector'
+  #   Projector::Client.configure do |client|
+  #     client[:host] = 'https://api.projector.com'
+  #     client[:token] = '<YOUR-API-TOKEN>'
+  #   end
   class Client
     include Projector::ApiMethods
     include Projector::Transport::HTTP
 
-    attr_accessor :host, :token, :result_format
+    attr_accessor :token, :result_format
 
     # The current configuration parameters for all clients
     def self.options
@@ -19,19 +34,25 @@
       }
     end
 
-    # Sets the current configuration parameters for all clients
+    # Replaces the global Projector client options
+    #
+    # @param [Hash] val the parameters to store
     def self.options=(val)
       @options = val
     end
 
-    # Allows the setting of configuration parameters in a configure block.
+    # Configure the global Projector client options using a block
+    #
+    # @yield [Hash] a hash of configuration values for the Projector Client
     def self.configure
       yield options
     end
 
     # Initialize a new client.
     #
-    # @param options [Hash] optionally specify `:access_token`, `:host`, `:api_version`
+    # @param [Hash] options
+    # @option options [String] :access_token The API access token
+    # @option options [String] :host The API host
     def initialize(options = {})
       options = self.class.options.merge(options)
       @host = options[:host] || ENV['PROJECTOR_API_HOST']
@@ -39,8 +60,9 @@
       @options = options
     end
 
+    # The Projector API Host
     def host
-       @options[:host]
+      @options[:host]
     end
   end
 end

data/lib/projector/end_user.rb

@@ -1,10 +1,11 @@
 module Projector
+  # Internally represents an End User in your application.
   class EndUser
-
-    SCHEMA = 'http://schemas.projector.com/schemas/com.projector/server_api/jsonschema/0-9-2#/definitions/end_user_post'
-
     attr_accessor :id, :tags
 
+    # @param [Hash] params Properties for a user
+    # @option params [String] :id the id of the user in your application
+    # @option params [Array] :tags an array of tags to apply to the user
     def initialize(params = {})
       raise Projector::InvalidEndUser.new("Invalid end user, id missing") if params[:id].nil?
       if params.instance_of?(Hash)
@@ -16,6 +17,8 @@ module Projector
       end
     end
 
+    # Serializes the EndUser object to the correct Projector-defined hash format.
+    # @return [Hash]
     def to_hash
       basic_hash = {
                       id: self.id.to_s,

data/lib/projector/envelope.rb

@@ -1,22 +1,25 @@
 module Projector
+  # Wraps all requests to the Projector API in an envelope specifying data as an explicit parameter.
   class Envelope
     attr_accessor :schema, :data
 
-    def initialize(schema, data)
-      @schema = schema
+    # @param [Object] data the data hash or array containing parameters for the API call
+    def initialize(data)
       @data = data
     end
 
+    # Returns the payload of the envelope
+    # @return [Object]
     def payload
       data.respond_to?(:to_hash) ? data.to_hash : data
     end
 
+    # Serializes the envelope to the correct Projector-defined envelope hash format
     def to_hash(params = {})
-      raise Projector::InvalidEnvelope unless @data && @schema
+      raise Projector::InvalidEnvelope unless @data
       {
-        schema: schema,
         data: payload
       }
     end
   end
-end
+end

data/lib/projector/error.rb

@@ -1,61 +1,57 @@
 module Projector
-  # Standard Projector error
+  # Standard Projector error.
   class Error < StandardError
-    attr_accessor :request, :response, :response_body, :request_id
+    # The request object for the request
+    attr_accessor :request
+    # The response object (if present)
+    attr_accessor :response
+    # The http response body, if present
+    attr_accessor :response_body
+    # The Projector API request id
+    attr_accessor :request_id
   end
 
-  # Raised when Projector returns a 400 HTTP status code
+  # Raised when Projector returns a 400 HTTP status code.
   class BadRequest < Error; end
 
-  # Raised when Projector returns a 401 HTTP status code
+  # Raised when Projector returns a 401 HTTP status code.
   class Unauthorized < Error; end
 
-  # Raised when Projector returns a 403 HTTP status code
+  # Raised when Projector returns a 403 HTTP status code.
   class Forbidden < Error; end
 
-  # Raised when Projector returns a 404 HTTP status code
+  # Raised when Projector returns a 404 HTTP status code.
   class NotFound < Error; end
 
-  # Raised when Projector returns a 406 HTTP status code
+  # Raised when Projector returns a 406 HTTP status code.
   class NotAcceptable < Error; end
 
-  # Raised when Projector returns a 422 HTTP status code
+  # Raised when Projector returns a 422 HTTP status code.
   class UnprocessableEntity < Error; end
 
-  # Raised when Projector returns a 500 HTTP status code
+  # Raised when Projector returns a 500 HTTP status code.
   class InternalServerError < Error;
     attr_accessor :retry_after
   end
 
-  # Raised when Projector returns a 501 HTTP status code
+  # Raised when Projector returns a 501 HTTP status code.
   class NotImplemented < Error; end
 
-  # Raised when Projector returns a 502 HTTP status code
+  # Raised when Projector returns a 502 HTTP status code.
   class BadGateway < Error; end
 
-  # Raised when Projector returns a 503 HTTP status code
+  # Raised when Projector returns a 503 HTTP status code.
   class ServiceUnavailable < Error; end
 
-  # Raised when a unique ID is required but not provided
+  # Raised when a unique ID is required but not provided.
   class UniqueIDRequired < Error; end
 
+  # Raised when an invalid End User is sumbitted to the Projector API.
   class InvalidEndUser < StandardError; end
+
+  # Raised when an invalid event is submitted to the Projector API.
   class InvalidEvent < StandardError; end
-  class InvalidDevice < StandardError; end
-  class InvalidRegistration < StandardError; end
-  class InvalidEnvelope < StandardError; end
 
-  # Status code to exception map
-  ERROR_MAP = {
-    400 => Projector::BadRequest,
-    401 => Projector::Unauthorized,
-    403 => Projector::Forbidden,
-    404 => Projector::NotFound,
-    406 => Projector::NotAcceptable,
-    422 => Projector::UnprocessableEntity,
-    500 => Projector::InternalServerError,
-    501 => Projector::InternalServerError,
-    502 => Projector::InternalServerError,
-    503 => Projector::InternalServerError
-  }
+  # Raised when an invalid envelope is submitted to the Projector API.
+  class InvalidEnvelope < StandardError; end
 end

data/lib/projector/event.rb

@@ -1,13 +1,20 @@
 module Projector
   require 'securerandom'
 
+  # Internally represents an event being sent to the Projector API.
   class Event
-    SCHEMA = 'http://schemas.projector.com/schemas/com.projector/events_api/jsonschema/0-9-3#/links/0/schema'
-
+    
+    # @param [Hash] params a hash of properties to send with the event
+    # @option params [String] id (SecureRandom.uuid) the unique identifier for this event in your system
+    # @option params [Number] event_time (Time.now) the ms since epoch for this event
+    # @option params [Hash] event_context data providing context for the event. Used in delivery rules, templates, and more at Projector.
+    # @option params [Hash] target containing either an *end_users* or *tags* key and a corresponding hash of values.
     def initialize(params)
       @params = params.inject({}){|memo,(k,v)| memo[k.to_sym] = v; memo}
     end
 
+   # Serializes the Event object to the correct Projector-defined hash format.
+    # @return [Hash]
     def to_hash
       overrides = {
         id: @params[:id] ? @params[:id].to_s : SecureRandom.uuid,

data/lib/projector/transport/http.rb

@@ -1,13 +1,31 @@
 module Projector
+  # Abstracted network transports for communicating to the Projector API.
+  # @api private
   module Transport
-    # Persistent HTTP API transport adapter
+    # Persistent HTTP API transport adapter.
     module HTTP
       require 'net/http/persistent'
       require 'uri'
       require 'json'
+      require 'projector/error'
 
+      # Maximum URI redrects to follow before failing.
       MAX_REDIRECTS = 2
 
+      # Status code to exception map.
+      ERROR_MAP = {
+        400 => Projector::BadRequest,
+        401 => Projector::Unauthorized,
+        403 => Projector::Forbidden,
+        404 => Projector::NotFound,
+        406 => Projector::NotAcceptable,
+        422 => Projector::UnprocessableEntity,
+        500 => Projector::InternalServerError,
+        501 => Projector::InternalServerError,
+        502 => Projector::InternalServerError,
+        503 => Projector::InternalServerError
+      }
+
       [:get, :post, :put, :delete, :patch].each do |method|
         define_method method do |*args|
           json_request(method, *args)
@@ -16,6 +34,13 @@ module Projector
 
       protected
 
+      # Makes an HTTP Request
+      #
+      # @param [String] method The HTTP method to use
+      # @param [String] host the host to connect to
+      # @param [String] path the path to request
+      # @param [Hash] params (nil) the parameters to send
+      # @param [Integer] redirect_count (0) the number of redirects that have been followed so far
       def request(method, host, path, params = nil, redirect_count = 0)
         uri = URI.parse("#{host}#{path}")
 
@@ -73,6 +98,8 @@ module Projector
         response
       end
 
+      # Returns an instance of the HTTP client
+      # @return [Net::HTTP::Persistent]
       def http
         @http ||= begin
                     http = Net::HTTP::Persistent.new('projector')
@@ -82,6 +109,9 @@ module Projector
                   end
       end
 
+      # Constructs a request object based off the method
+      # @param [Symbol] method the HTTP method
+      # @param [String] uri the HTTP URI to request
       def build_request(method, uri)
         case method
           when :get
@@ -97,6 +127,9 @@ module Projector
         end
       end
 
+      # Converts a hash to HTTP URI format
+      # @param [Hash] hash the hash to be converted
+      # @return [String]
       def to_url_params(hash)
         params = []
         hash.each_pair do |key, value|
@@ -105,6 +138,7 @@ module Projector
         params.sort.join('&')
       end
 
+      # Escapes params to a URI-safe form
       def param_for(key, value, parent = nil)
         if value.is_a?(Hash)
           params = []
@@ -118,12 +152,14 @@ module Projector
         end
       end
 
+      # Raises the appropriate error based on the {ERROR_MAP}
+      # raise [Projector::Error]
       def handle_error(request, response)
-        return unless error = Projector::ERROR_MAP[response.code.to_i]
+        return unless error = ERROR_MAP[response.code.to_i]
         message = nil
         begin
           message = JSON.parse(response.body) || request.path
-        rescue JSON::ParserError => e
+        rescue JSON::ParserError
         end
         # Raise error
         err = error.new(message)
@@ -135,20 +171,27 @@ module Projector
         raise err
       end
 
+      # Makes a request and parses the result as a JSON object
+      # @return [Response]
       def json_request(*args)
         # Perform request, pass result format
         Response.new(request(*args))
       end
 
+      # Returns true if the request is not an error or redirect
+      # @return [Boolean]
       def boolean_from_response(*args)
         response = request(*args)
         (200..299).include? response.code.to_i
       end
 
+      # Returns true if the HTTP method can post data
+      # @return [Boolean]
       def can_post_data?(method)
         [:post, :put, :patch].include?(method)
       end
 
+      # Logs all HTTP request data to STDOUT if the PROJECTOR_DEBUG_HTTP env variable is set 
       def log_debug_data(*args)
         return unless ENV['PROJECTOR_DEBUG_HTTP']
         @logger ||= begin
@@ -190,14 +233,16 @@ module Projector
           # Parse JSON
           begin
             self.body = JSON.parse(response_body)
-          rescue JSON::ParserError => ex
+          rescue JSON::ParserError
             self.body = response_body
           end
         end
       end
 
-      class TooManyRedirectsError < StandardError
-        attr_accessor :request, :response, :redirect_count
+      # Raised when the HTTP client follows too many HTTP redirects
+      class TooManyRedirectsError < Projector::Error
+        # The redirect count that caused this error
+        attr_accessor :redirect_count
       end
     end
   end

data/lib/projector/version.rb

@@ -1,4 +1,7 @@
 module Projector
-  VERSION = "1.0.2"
+  # Current SDK Version
+  VERSION = "1.0.3"
+
+  # Current API Version
   API_VERSION = 1
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: projector
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Projector
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-17 00:00:00.000000000 Z
+date: 2016-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: net-http-persistent
@@ -38,8 +38,10 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".yardopts"
 - Gemfile
 - LICENSE
+- Overview.md
 - README.md
 - Rakefile
 - bin/console
@@ -81,9 +83,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.1
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Ruby SDK for interacting with the Projector SDK
 test_files: []
-has_rdoc: