parse-stack 1.5.1 → 1.5.2

data/lib/parse/query/ordering.rb

@@ -1,17 +1,30 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-# Ordering is implemented similarly as constraints in which we add
-# special methods to the Symbol class. The developer can then pass one
-# or an array of fields (as symbols) and call the particular ordering
-# polarity (ex. :name.asc would create a Parse::Order where we want
-# things to be sortd by the name field in ascending order)
-# For more information about the query design pattern from DataMapper
-# that inspired this, see http://datamapper.org/docs/find.html
+
 module Parse
+    # This class adds support for describing ordering for Parse queries. You can
+    # either order by ascending (asc) or descending (desc) order.
+    #
+    # Ordering is implemented similarly to constraints in which we add
+    # special methods to the Symbol class. The developer can then pass one
+    # or an array of fields (as symbols) and call the particular ordering
+    # polarity (ex. _:name.asc_ would create a Parse::Order where we want
+    # things to be sortd by the name field in ascending order)
+    # For more information about the query design pattern from DataMapper
+    # that inspired this, see http://datamapper.org/docs/find.html'
+    # @example
+    #   :name.asc # => Parse::Order by ascending :name
+    #   :like_count.desc # => Parse::Order by descending :like_count
+    #
     class Order
-      # We only support ascending and descending
+      # The Parse operators to indicate ordering direction.
       ORDERING = {asc: '', desc: '-'}.freeze
+      # @!attribute [rw] field
+      #   @return [Symbol] the name of the field
+      # @!attribute [rw] direction
+      #   The direction of the sorting. This is either `:asc` or `:desc`.
+      #   @return [Symbol]
       attr_accessor :field, :direction
 
       def initialize(field, order = :asc)

data/lib/parse/stack.rb

@@ -7,6 +7,7 @@ require_relative 'query'
 require_relative 'model/object'
 require_relative 'webhooks'
 
+
 module Parse
   module Stack
 

data/lib/parse/stack/version.rb

@@ -2,7 +2,8 @@
 # frozen_string_literal: true
 
 module Parse
+  # @author Anthony Persaud
   module Stack
-    VERSION = "1.5.1"
+    VERSION = "1.5.2"
   end
 end

data/lib/parse/webhooks.rb

@@ -14,30 +14,6 @@ require_relative 'model/object'
 require_relative 'webhooks/payload'
 require_relative 'webhooks/registration'
 
-
-=begin
-  Some methods take a block, and this pattern frequently appears for a block:
-
-  {|x| x.foo}
-  and people would like to write that in a more concise way. In order to do that,
-   a symbol, the method Symbol#to_proc, implicit class casting, and & operator
-   are used in combination. If you put & in front of a Proc instance in the
-   argument position, that will be interpreted as a block. If you combine
-   something other than a Proc instance with &, then implicit class casting
-   will try to convert that to a Proc instance using to_proc method defined on
-   that object if there is any. In case of a Symbol instance, to_proc works in
-   this way:
-
-    :foo.to_proc # => ->x{x.foo}
-
-   For example, suppose you write like this:
-
-    bar(&:foo)
-   The & operator is combined with :foo, which is not a Proc instance, so implicit class cast applies Symbol#to_proc to it, which gives ->x{x.foo}. The & now applies to this and is interpreted as a block, which gives:
-
-   bar{|x| x.foo}
-=end
-
 module Parse
 
   class Object

data/lib/parse/webhooks/payload.rb

@@ -10,7 +10,12 @@ require 'active_support/core_ext'
 require 'active_model_serializers'
 
 module Parse
-
+    # Represents the data structure that Parse server sends to a registered webhook.
+    # Parse Parse allows you to receive Cloud Code webhooks on your own hosted
+    # server. The `Parse::Webhooks` class is a lightweight Rack application that
+    # routes incoming Cloud Code webhook requests and payloads to locally
+    # registered handlers. The payloads are `Parse::Payload` type of objects that
+    # represent that data that Parse sends webhook handlers.
     class Payload
     ATTRIBUTES = { master: nil, user: nil,
            installationId: nil, params: nil,
@@ -18,6 +23,31 @@ module Parse
                  original: nil, update: nil,
                  triggerName: nil }.freeze
     include ::ActiveModel::Serializers::JSON
+    # @!attribute [rw] master
+    #   @return [Boolean] whether the master key was used for this request.
+    # @!attribute [rw] user
+    #   @return [Parse::User] the user who performed this request or action.
+    # @!attribute [rw] installation_id
+    #   @return [String] The identifier of the device that submitted the request.
+    # @!attribute [rw] params
+    #   @return [Hash] The list of function arguments submitted for a function request.
+    # @!attribute [rw] function_name
+    #   @return [String] the name of the function.
+    # @!attribute [rw] object
+    #  In a beforeSave, this attribute is the final object that will be persisted.
+    #  @return [Hash] the object hash related to a webhook trigger request.
+    #  @see #parse_object
+    # @!attribute [rw] trigger_name
+    #  @return [String] the name of the trigger (ex. beforeSave, afterSave, etc.)
+    # @!attribute [rw] original
+    #  In a beforeSave, for previously saved objects, this attribute is the Parse::Object
+    #  that was previously in the persistent store.
+    #  @return [Hash] the object hash related to a webhook trigger request.
+    #  @see #parse_object
+    # @!attribute [rw] raw
+    #   @return [Hash] the raw payload from Parse server.
+    # @!attribute [rw] update
+    #   @return [Hash] the update payload in the request.
     attr_accessor :master, :user, :installation_id, :params, :function_name, :object, :trigger_name
 
     attr_accessor :original, :update, :raw
@@ -25,6 +55,9 @@ module Parse
     alias_method :functionName, :function_name
     alias_method :triggerName, :trigger_name
 
+    # You would normally never create a Parse::Payload object since it is automatically
+    # provided to you when using Parse::Webhooks.
+    # @see Parse::Webhooks
     def initialize(hash = {})
       hash = JSON.parse(hash) if hash.is_a?(String)
       hash = Hash[hash.map{ |k, v| [k.to_s.underscore.to_sym, v] }]
@@ -33,6 +66,7 @@ module Parse
       @user = Parse::User.new hash[:user] if hash[:user].present?
       @installation_id = hash[:installation_id]
       @params = hash[:params]
+      @params = @params.with_indifferent_access if @params.is_a?(Hash)
       @function_name = hash[:function_name]
       @object = hash[:object]
       @trigger_name = hash[:trigger_name]
@@ -40,61 +74,80 @@ module Parse
       @update = hash[:update] || {} #it comes as an update hash
     end
 
+    # @return [Hash]
     def attributes
       ATTRIBUTES
     end
 
+    # true if this is a webhook function request.
     def function?
       @function_name.present?
     end
 
+    # @return [String] the name of the Parse class for this request.
     def parse_class
       return nil unless @object.present?
       @object[Parse::Model::KEY_CLASS_NAME] || @object[:className]
     end
 
+    # @return [String] the objectId in this request.
     def parse_id
       return nil unless @object.present?
       @object[Parse::Model::OBJECT_ID] || @object[:objectId]
     end; alias_method :objectId, :parse_id
 
+    # true if this is a webhook trigger request.
     def trigger?
       @trigger_name.present?
     end
 
+    # true if this is a beforeSave or beforeDelete webhook trigger request.
     def before_trigger?
       before_save? || before_delete?
     end
 
+    # true if this is a afterSave or afterDelete webhook trigger request.
     def after_trigger?
       after_save? || after_delete?
     end
 
+    # true if this is a beforeSave webhook trigger request.
     def before_save?
       trigger? && @trigger_name.to_sym == :beforeSave
     end
 
+    # true if this is a afterSave webhook trigger request.
     def after_save?
       trigger? && @trigger_name.to_sym == :afterSave
     end
 
+    # true if this is a beforeDelete webhook trigger request.
     def before_delete?
       trigger? && @trigger_name.to_sym == :beforeDelete
     end
 
+    # true if this is a afterDelete webhook trigger request.
     def after_delete?
       trigger? && @trigger_name.to_sym == :afterDelete
     end
 
+    # true if this request is a trigger that contains an object.
     def object?
       trigger? && @object.present?
     end
 
+    # @return [Parse::Object] a Parse::Object from the original object
     def original_parse_object
       return nil unless @original.is_a?(Hash)
       Parse::Object.build(@original)
     end
 
+    # This method returns a Parse::Object by combining the original object, if was provided,
+    # with the final object. This will return a dirty tracked Parse::Object subclass,
+    # that will have information on which fields have changed between the previous state
+    # in the persistent store and the one about to be saved.
+    # @param pristine [Boolean] whether the object should be returned without dirty tracking.
+    # @return [Parse::Object] a dirty tracked Parse::Object subclass instance
     def parse_object(pristine = false)
       return nil unless object?
       return Parse::Object.build(@object) if pristine

data/lib/parse/webhooks/registration.rb

@@ -15,7 +15,7 @@ module Parse
 
       ALLOWED_HOOKS = Parse::API::Hooks::TRIGGER_NAMES + [:function]
 
-
+      # removes all registered webhook functions with Parse Server.
       def remove_all_functions!
 
           client.functions.results.sort_by { |f| f['functionName'] }.each do |f|
@@ -25,6 +25,7 @@ module Parse
           end
       end
 
+      # removes all registered webhook triggers with Parse Server.
       def remove_all_triggers!
 
         client.triggers.results.sort_by { |f| [f['triggerName'],f['className']] }.each do |f|
@@ -37,6 +38,8 @@ module Parse
 
       end
 
+      # Registers all webhook functions registered with Parse::Stack with Parse server.
+      # @param endpoint [String] a https url that points to the webhook server.
       def register_functions!(endpoint)
 
         unless endpoint.present? && endpoint.starts_with?('https://')
@@ -62,6 +65,9 @@ module Parse
 
       end
 
+      # Registers all webhook triggers registered with Parse::Stack with Parse server.
+      # @param endpoint [String] a https url that points to the webhook server.
+      # @param include_wildcard [Boolean] Allow wildcard registrations
       def register_triggers!(endpoint, include_wildcard: false)
 
         unless endpoint.present? && endpoint.starts_with?('https://')
@@ -87,7 +93,7 @@ module Parse
           classNames = routes[trigger].keys.dup
           if include_wildcard && classNames.include?('*') #then create the list for all classes
             classNames.delete '*' #delete the wildcard before we expand it
-            classNames = classNames + Parse.registered_classes
+            classNames = classNames + Parse.registered_classes - ['_Session']
             classNames.uniq!
           end
 
@@ -106,6 +112,11 @@ module Parse
         end
       end
 
+      # Registers a webhook trigger with a given endpoint url.
+      # @param trigger [Symbol] Trigger type based on Parse::API::Hooks::TRIGGER_NAMES or :function.
+      # @param name [String] the name of the webhook.
+      # @param url [String] the https url endpoint that will handle the request.
+      # @see Parse::API::Hooks::TRIGGER_NAMES
       def register_webhook!(trigger, name, url)
         trigger = trigger.to_s.camelize(:lower).to_sym
         raise ArgumentError, "Invalid hook trigger #{trigger}" unless ALLOWED_HOOKS.include?(trigger)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: parse-stack
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: 1.5.2
 platform: ruby
 authors:
 - Anthony Persaud
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-09-29 00:00:00.000000000 Z
+date: 2016-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel