parse-stack 1.5.1 → 1.5.2

data/lib/parse/model/classes/role.rb

@@ -3,12 +3,17 @@
 require_relative '../object'
 require_relative 'user'
 module Parse
-
+  # This class represents the data and columns contained in the standard Parse `_Role` collection.
   class Role < Parse::Object
+    
     parse_class Parse::Model::CLASS_ROLE
+    # @return [String] the name of this role.
     property :name
-
+    # The roles Parse relation provides a mechanism to create a hierarchical inheritable types of permissions
+    # by assigning child roles.
+    # @return [RelationCollectionProxy<Role>] a collection of Roles.
     has_many :roles, through: :relation
+    # @return [RelationCollectionProxy<User>] a Parse relation of users belonging to this role.
     has_many :users, through: :relation
 
     before_save do

data/lib/parse/model/classes/session.rb

@@ -3,20 +3,37 @@
 require_relative '../object'
 
 module Parse
+  # This class represents the data and columns contained in the standard Parse
+  # `_Session` collection. The Session class maintains per-device (or website) authentication
+  # information for a particular user. Whenever a User object is logged in, a new Session record, with
+  # a session token is generated. You may use a known active session token to find the corresponding
+  # user for that session. Deleting a Session record (and session token), effectively logs out the user, when making Parse requests
+  # on behalf of the user using the session token.
   class Session < Parse::Object
+
     parse_class Parse::Model::CLASS_SESSION
+    # @return [Hash] data on how this Session was created.
     property :created_with, :object
+    # @return [Parse::Date] when the session token expires.
     property :expires_at, :date
+    # @return [String] The installation id from the Installation table.
+    # @see Installation#installation_id
     property :installation_id
+    # @return [Boolean] whether this session token is restricted.
     property :restricted, :boolean
+    # @return [String] the session token for this installation and user pair.
     property :session_token
-
+    # @return [User] the user corresponding to this session.
+    # @see User
     belongs_to :user
 
-    def self.session(token)
-      response = client.fetch_session(token)
+    # Return the Session record for this session token.
+    # @param token [String] the session token
+    # @return [Session] the session for this token, otherwise nil.
+    def self.session(token, **opts)
+      response = client.fetch_session(token, opts)
       if response.success?
-        reutrn Parse::Session.build response.result
+        return Parse::Session.build response.result
       end
       nil
     end

data/lib/parse/model/classes/user.rb

@@ -1,24 +1,52 @@
 # encoding: UTF-8
 # frozen_string_literal: true
 
-# The User class provided by Parse with the required fields. You may
-# add mixings to this class to add the app specific properties
 require_relative '../object'
 module Parse
-
-  class UsernameMissingError < StandardError; end; # 200
-  class PasswordMissingError < StandardError; end; # 201
-  class UsernameTakenError < StandardError; end; # 202
-  class EmailTakenError < StandardError; end; # 203
-  class EmailMissing < StandardError; end; # 204
-
+  # 200	Error code indicating that the username is missing or empty.
+  class UsernameMissingError < StandardError; end;
+  # 201	Error code indicating that the password is missing or empty.
+  class PasswordMissingError < StandardError; end;
+  # Error code 202: indicating that the username has already been taken.
+  class UsernameTakenError < StandardError; end;
+  # 203	Error code indicating that the email has already been taken.
+  class EmailTakenError < StandardError; end;
+  # 204	Error code indicating that the email is missing, but must be specified.
+  class EmailMissing < StandardError; end;
+  # 205	Error code indicating that a user with the specified email was not found.
+  class EmailNotFound < StandardError; end;
+  # 125	Error code indicating that the email address was invalid.
+  class InvalidEmailAddress < StandardError; end;
+
+  # The main class representing the _User table in Parse. A user can either be signed up or anonymous.
+  # All users need to have a username and a password, with email being optional but globally unique if set.
+  # You may add additional properties by redeclaring the class to match your specific schema.
   class User < Parse::Object
 
     parse_class Parse::Model::CLASS_USER
+    # @return [String] The session token if this user is logged in.
     attr_accessor :session_token
+
+    # The auth data for this Parse::User. Depending on how this user is authenticated or
+    # logged in, the contents may be different, especially if you are using another third-party
+    # authentication mechanism like Facebook/Twitter.
+    # @return [Hash] Auth data hash object.
     property :auth_data, :object
+
+    # Emails are optional in Parse, but if set, they must be unique.
+    # @return [String] The email field.
     property :email
+
+    # @overload password=(value)
+    # You may set a password for this user when you are creating them. Parse never returns a
+    # Parse::User's password when a record is fetched. Therefore, normally this getter is nil.
+    # While this API exists, it is recommended you use either the #login! or #signup! methods.
+    # (see #login!)
+    # @return [String] The password you set.
     property :password
+
+    # All Parse users have a username and must be globally unique.
+    # @return [String] The user's username.
     property :username
 
     before_save do
@@ -26,45 +54,71 @@ module Parse
       self.clear_attribute_change!(:acl)
     end
 
+    # True if this user is anonymous.
     def anonymous?
       anonymous_id.nil?
     end
 
+    # Returns the anonymous identifier only if this user is anonymous.
+    # @see #anonymous?
+    # @return [String] The anonymous identifier for this anonymous user.
     def anonymous_id
       auth_data['anonymous']['id'] if auth_data.present? && auth_data["anonymous"].is_a?(Hash)
     end
 
+    # Adds the third-party authentication data to for a given service.
+    # @param service_name [Symbol] The name of the service (ex. :facebook)
+    # @param data [Hash] The body of the OAuth data. Dependent on each service.
+    # @raise [ResponseError] If user was not successfully linked
     def link_auth_data!(service_name, **data)
       response = client.set_service_auth_data(id, service_name, data)
-      apply_attributes!(response.result) if response.success?
-      response.success?
+      raise Parse::ResponseError, response if response.error?
+      apply_attributes!(response.result)
     end
 
+    # Removes third-party authentication data for this user
+    # @param service_name [Symbol] The name of the third-party service (ex. :facebook)
+    # @raise [ResponseError] If user was not successfully unlinked
+    # @return [Boolean] True/false if successful.
     def unlink_auth_data!(service_name)
       response = client.set_service_auth_data(id, service_name, nil)
-      apply_attributes!(response.result) if response.success?
-      response.success?
+      raise Parse::ResponseError, response if response.error?
+      apply_attributes!(response.result)
     end
 
+
+    # @!visibility private
     # So that apply_attributes! works with session_token for login
     def session_token_set_attribute!(token, track = false)
       @session_token = token.to_s
     end
     alias_method :sessionToken_set_attribute!, :session_token_set_attribute!
 
+    # @return [Boolean] true if this user has a session token.
     def logged_in?
       self.session_token.present?
     end
 
+    # Request a password reset for this user
+    # @return [Boolean] true if it was successful requested. false otherwise.
     def request_password_reset
       return false if email.nil?
       Parse::User.request_password_reset(email)
     end
 
+    # You may set a password for this user when you are creating them. Parse never returns a
+    # @param passwd The user's password to be used for signing up.
+    # @raise [Parse::UsernameMissingError] If username is missing.
+    # @raise [Parse::PasswordMissingError] If password is missing.
+    # @raise [Parse::UsernameTakenError] If the username has already been taken.
+    # @raise [Parse::EmailTakenError] If the email has already been taken (or exists in the system).
+    # @raise [Parse::InvalidEmailAddress] If the email is invalid.
+    # @raise [Parse::ResponseError] An unknown error occurred.
+    # @return [Boolean] True if signup it was successful. If it fails an exception is thrown.
     def signup!(passwd = nil)
       self.password = passwd || password
       if username.blank?
-        raise Parse::UsernameMissingError, "Signup requires an username."
+        raise Parse::UsernameMissingError, "Signup requires a username."
       end
 
       if password.blank?
@@ -91,10 +145,15 @@ module Parse
         raise Parse::UsernameTakenError, response
       when Parse::Response::ERROR_EMAIL_TAKEN
         raise Parse::EmailTakenError, response
+      when Parse::Response::ERROR_EMAIL_INVALID
+        raise Parse::InvalidEmailAddress, response
       end
-      raise response
+      raise Parse::ResponseError, response
     end
 
+    # Login and get a session token for this user.
+    # @param passwd [String] The password for this user.
+    # @return [Boolean] True/false if we received a valid session token.
     def login!(passwd = nil)
       self.password = passwd || self.password
       response = client.login(username.to_s, password.to_s)
@@ -102,6 +161,8 @@ module Parse
       self.session_token.present?
     end
 
+    # Invalid the current session token for this logged in user.
+    # @return [Boolean] True/false if successful
     def logout
       return true if self.session_token.blank?
       client.logout session_token
@@ -111,11 +172,13 @@ module Parse
       false
     end
 
+    # @!visibility private
     def session_token=(token)
       @session = nil
       @session_token = token
     end
 
+    # @return [Session] the session corresponding to the user's session token.
     def session
       if @session.blank? && @session_token.present?
         response = client.fetch_session(@session_token)
@@ -124,6 +187,16 @@ module Parse
       @session
     end
 
+    # Creates a new Parse::User given a hash that maps to the fields defined in your Parse::User collection.
+    # @param body [Hash] The hash containing the Parse::User fields. The field `username` and `password` are required.
+    # @option opts [Boolean] :master_key Whether the master key should be used for this request.
+    # @raise [UsernameMissingError] If username is missing.
+    # @raise [PasswordMissingError] If password is missing.
+    # @raise [UsernameTakenError] If the username has already been taken.
+    # @raise [EmailTakenError] If the email has already been taken (or exists in the system).
+    # @raise [InvalidEmailAddress] If the email is invalid.
+    # @raise [ResponseError] An unknown error occurred.
+    # @return [User] Returns a successfully created Parse::User.
     def self.create(body, **opts)
       response = client.create_user(body, opts: opts)
       if response.success?
@@ -140,43 +213,70 @@ module Parse
       when Parse::Response::ERROR_EMAIL_TAKEN
         raise Parse::EmailTakenError, response
       end
-      raise response
+      raise  Parse::ResponseError, response
     end
 
-    # method will signup or login a user given the third-party authentication data
+    # Automatically and implicitly signup a user if it did not already exists and
+    # authenticates them (login) using third-party authentication data. May raise exceptions
+    # similar to `create` depending on what you provide the _body_ parameter.
+    # @param service_name [Symbol] the name of the service key (ex. :facebook)
+    # @param auth_data [Hash] the specific service data to place in the user's auth-data for this service.
+    # @param body [Hash] any additional User related fields or properties when signing up this User record.
+    # @return [User] a logged in user, or nil.
+    # @see User.create
     def self.autologin_service(service_name, auth_data, body: {})
       body = body.merge({authData: {service_name => auth_data} })
       self.create(body)
     end
 
+    # This method will signup a new user using the parameters below. The required fields
+    # to create a user in Parse is the _username_ and _password_ fields. The _email_ field is optional.
+    # Both _username_ and _email_ (if provided), must be unique. At a minimum, it is recommended you perform
+    # a query using the supplied _username_ first to verify do not already have an account with that username.
+    # This method will raise all the exceptions from the similar `create` method.
+    # @see User.create
     def self.signup(username, password, email = nil, body: {})
       body = body.merge({username: username, password: password })
       body[:email] = email if email.present?
       self.create(body)
     end
 
+    # Login and return a Parse::User with this username/password combination.
+    # @param username [String] the user's username
+    # @param password [String] the user's password
+    # @return [User] a logged in user for the provided username. Returns nil otherwise.
     def self.login(username, password)
       response = client.login(username.to_s, password.to_s)
       response.success? ? Parse::User.build(response.result) : nil
     end
 
+    # Request a password reset for a registered email.
+    # @param email [String] The user's email address.
+    # @return [Boolean] True/false if successful.
     def self.request_password_reset(email)
       email = email.email if email.is_a?(Parse::User)
       return false if email.blank?
-      response = client.reset_password(email)
+      response = client.request_password_reset(email)
       response.success?
     end
 
-    def self.session(token)
-      self.session! token
+    # Same as `session!` but returns nil if a user was not found or sesion token was invalid.
+    # @return [User] the user matching this active token, otherwise nil.
+    # @see #session!
+    def self.session(token, opts = {})
+      self.session! token, opts
     rescue InvalidSessionTokenError => e
       nil
     end
 
-    def self.session!(token)
+    # Return a Parse::User for this active session token.
+    # @raise [InvalidSessionTokenError] Invalid session token.
+    # @return [User] the user matching this active token
+    # @see #session
+    def self.session!(token, opts = {})
       # support Parse::Session objects
       token = token.session_token if token.respond_to?(:session_token)
-      response = client.current_user(token)
+      response = client.current_user(token, opts)
       response.success? ? Parse::User.build(response.result) : nil
     end
 

data/lib/parse/model/core/actions.rb

@@ -9,7 +9,6 @@ require 'time'
 require 'parallel'
 require_relative '../../client/request'
 
-#This module provides many of the CRUD operations on Parse::Object.
 
 # A Parse::RelationAction is special operation that adds one object to a relational
 # table as to another. Depending on the polarity of the action, the objects are
@@ -46,8 +45,13 @@ end
 # we use temporary Request objects have contain the operation to be performed (in some cases).
 # This allows to group a list of Request methods, into a batch for sending all at once to Parse.
 module Parse
+
+  # An error raised when a save failure occurs.
   class SaveFailureError < StandardError
+    # @return [Parse::Object] the Parse::Object that failed to save.
     attr_reader :object
+
+    # @param object [Parse::Object] the object that failed.
     def initialize(object)
       @object = object
     end
@@ -455,8 +459,8 @@ module Parse
   module Fetching
 
     # force fetches the current object with the data contained in Parse.
-    def fetch!
-      response = client.fetch_object(parse_class, id)
+    def fetch!(opts = {})
+      response = client.fetch_object(parse_class, id, opts)
       if response.error?
         puts "[Fetch Error] #{response.code}: #{response.error}"
       end

data/lib/parse/model/core/properties.rb

@@ -13,17 +13,16 @@ require 'active_model_serializers'
 require 'active_support/hash_with_indifferent_access'
 require 'time'
 
-=begin
-This module provides support for handling all the different types of column data types
-supported in Parse and mapping them between their remote names with their local ruby named attributes.
-By default, the convention used for naming parameters is that the remote column should be in lower-first-camelcase, (ex. myField, eventAddress), except for
-a few special columns like "id" and "acl".
-Properties are defined when creating subclasses of Parse::Object and using the `property` class method.
 
-By defining properties, dynamic methods are created in order to allow getters and setters to be used. We will go into detail below.
-
-Each class will have a different copy of attribute mapping and field mappings.
-=end
+# This module provides support for handling all the different types of column data types
+# supported in Parse and mapping them between their remote names with their local ruby named attributes.
+# By default, the convention used for naming parameters is that the remote column should be in lower-first-camelcase, (ex. myField, eventAddress), except for
+# a few special columns like "id" and "acl".
+# Properties are defined when creating subclasses of Parse::Object and using the `property` class method.
+#
+# By defining properties, dynamic methods are created in order to allow getters and setters to be used. We will go into detail below.
+#
+# Each class will have a different copy of attribute mapping and field mappings.
 
 module Parse
 
@@ -206,7 +205,7 @@ module Parse
 
             method_name = add_suffix ? :"valid_#{prefix_or_key}?" : :"#{prefix_or_key}_valid?"
             define_method(method_name) do
-              value = instance_variable_get(ivar)
+              value = send(key) # call default getter
               return true if allow_nil && value.nil?
               enum_values.include?(value.to_s.to_sym)
             end
@@ -220,8 +219,10 @@ module Parse
                 method_name = :"#{prefix}_#{enum}"
               end
               self.scope method_name, ->(ex = {}){ ex.merge!(key => enum); query( ex )  }
-              define_method("#{method_name}!") { instance_variable_set(ivar, enum) }
-              define_method("#{method_name}?") { enum == instance_variable_get(ivar).to_s.to_sym }
+
+
+              define_method("#{method_name}!") { send set_attribute_method, enum, true }
+              define_method("#{method_name}?") { enum == send(key).to_s.to_sym }
             end
           end # unless scopes
 

data/lib/parse/model/core/querying.rb

@@ -3,8 +3,6 @@
 
 require_relative '../../query'
 
-# This module provides most of the querying methods for Parse Objects.
-# It proxies much of the query methods to the Parse::Query object.
 module Parse
 
   module Querying
@@ -38,17 +36,21 @@ module Parse
 
           if _q.is_a?(Parse::Query)
             klass = self
-            _q.define_singleton_method(:method_missing) do |m, *args, &block|
+            _q.define_singleton_method(:method_missing) do |m, *args, &chained_block|
               if klass.respond_to?(m, true)
-                klass_scope = klass.send(m, *args, &block)
+                # must be a scope
+                klass_scope = klass.send(m, *args)
                 if klass_scope.is_a?(Parse::Query)
-                  return self.add_constraints( klass_scope.constraints )
-                end
+                  # merge constraints
+                  add_constraints( klass_scope.constraints )
+                  # if a block was passed, execute the query, otherwise return the query
+                  return chained_block.present? ? results(&chained_block) : self
+                end # if
                 klass = nil # help clean up ruby gc
                 return klass_scope
               end
               klass = nil # help clean up ruby gc
-              return self.results.send(m, *args, &block)
+              return results.send(m, *args, &chained_block)
             end
           end
           return _q if block.nil?
@@ -61,6 +63,7 @@ module Parse
       # This query method helper returns a Query object tied to a parse class.
       # The parse class should be the name of the one that will be sent in the query
       # request pointing to the remote table.
+
       def query(constraints = {})
         Parse::Query.new self.parse_class, constraints
       end; alias_method :where, :query
@@ -71,6 +74,7 @@ module Parse
 
       # Most common method to use when querying a class. This takes a hash of constraints
       # and conditions and returns the results.
+
       def all(constraints = {})
         constraints = {limit: :max}.merge(constraints)
         prepared_query = query(constraints)
@@ -82,6 +86,7 @@ module Parse
       # then we treat it as a count.
       # Ex. Object.first( :name => "Anthony" ) (returns single object)
       # Ex. Object.first(3) # first 3 objects (array of 3 objects)
+
       def first(constraints = {})
         fetch_count = 1
         if constraints.is_a?(Numeric)
@@ -95,18 +100,19 @@ module Parse
       end
 
       # creates a count request (which is more performant when counting objects)
-      def count(**constraints)
+      
+      def count(constraints = {})
         query(constraints).count
       end
 
-      def newest(**constraints)
+      def newest(constraints = {})
         constraints.merge!(order: :created_at.desc)
         _q = query(constraints)
         _q.define_singleton_method(:method_missing) { |m, *args, &block| self.results.send(m, *args, &block) }
         _q
       end
 
-      def oldest(**constraints)
+      def oldest(constraints = {})
         constraints.merge!(order: :created_at.asc)
         _q = query(constraints)
         _q.define_singleton_method(:method_missing) { |m, *args, &block| self.results.send(m, *args, &block) }