parse-stack 1.5.1 → 1.5.2

data/lib/parse/client/protocol.rb

@@ -19,4 +19,51 @@ module Parse
       CONTENT_TYPE_FORMAT = 'application/json; charset=utf-8'
   end
 
+  module ErrorCodes
+    # OtherCause	-1	Error code indicating that an unknown error or an error unrelated to Parse occurred.
+    # InternalServerError	1	Error code indicating that something has gone wrong with the server. If you get this error code, it is Parse's fault. Please report the bug to https://parse.com/help.
+    # ConnectionFailed	100	Error code indicating the connection to the Parse servers failed.
+    # ObjectNotFound	101	Error code indicating the specified object doesn't exist.
+    # InvalidQuery	102	Error code indicating you tried to query with a datatype that doesn't support it, like exact matching an array or object.
+    # InvalidClassName	103	Error code indicating a missing or invalid classname. Classnames are case-sensitive. They must start with a letter, and a-zA-Z0-9_ are the only valid characters.
+    # MissingObjectId	104	Error code indicating an unspecified object id.
+    # InvalidKeyName	105	Error code indicating an invalid key name. Keys are case-sensitive. They must start with a letter, and a-zA-Z0-9_ are the only valid characters.
+    # InvalidPointer	106	Error code indicating a malformed pointer. You should not see this unless you have been mucking about changing internal Parse code.
+    # InvalidJSON	107	Error code indicating that badly formed JSON was received upstream. This either indicates you have done something unusual with modifying how things encode to JSON, or the network is failing badly.
+    # CommandUnavailable	108	Error code indicating that the feature you tried to access is only available internally for testing purposes.
+    # NotInitialized	109	You must call Parse.initialize before using the Parse library.
+    # IncorrectType	111	Error code indicating that a field was set to an inconsistent type.
+    # InvalidChannelName	112	Error code indicating an invalid channel name. A channel name is either an empty string (the broadcast channel) or contains only a-zA-Z0-9_ characters and starts with a letter.
+    # PushMisconfigured	115	Error code indicating that push is misconfigured.
+    # ObjectTooLarge	116	Error code indicating that the object is too large.
+    # OperationForbidden	119	Error code indicating that the operation isn't allowed for clients.
+    # CacheMiss	120	Error code indicating the result was not found in the cache.
+    # InvalidNestedKey	121	Error code indicating that an invalid key was used in a nested JSONObject.
+    # InvalidFileName	122	Error code indicating that an invalid filename was used for ParseFile. A valid file name contains only a-zA-Z0-9_. characters and is between 1 and 128 characters.
+    # InvalidACL	123	Error code indicating an invalid ACL was provided.
+    # Timeout	124	Error code indicating that the request timed out on the server. Typically this indicates that the request is too expensive to run.
+    # InvalidEmailAddress	125	Error code indicating that the email address was invalid.
+    # DuplicateValue	137	Error code indicating that a unique field was given a value that is already taken.
+    # InvalidRoleName	139	Error code indicating that a role's name is invalid.
+    # ExceededQuota	140	Error code indicating that an application quota was exceeded. Upgrade to resolve.
+    # ScriptFailed	141	Error code indicating that a Cloud Code script failed.
+    # ValidationFailed	142	Error code indicating that a Cloud Code validation failed.
+    # FileDeleteFailed	153	Error code indicating that deleting a file failed.
+    # RequestLimitExceeded	155	Error code indicating that the application has exceeded its request limit.
+    # InvalidEventName	160	Error code indicating that the provided event name is invalid.
+    # UsernameMissing	200	Error code indicating that the username is missing or empty.
+    # PasswordMissing	201	Error code indicating that the password is missing or empty.
+    # UsernameTaken	202	Error code indicating that the username has already been taken.
+    # EmailTaken	203	Error code indicating that the email has already been taken.
+    # EmailMissing	204	Error code indicating that the email is missing, but must be specified.
+    # EmailNotFound	205	Error code indicating that a user with the specified email was not found.
+    # SessionMissing	206	Error code indicating that a user object without a valid session could not be altered.
+    # MustCreateUserThroughSignup	207	Error code indicating that a user can only be created through signup.
+    # AccountAlreadyLinked	208	Error code indicating that an an account being linked is already linked to another user.
+    # InvalidSessionToken	209	Error code indicating that the current session token is invalid.
+    # LinkedIdMissing	250	Error code indicating that a user cannot be linked to an account because that account's id could not be found.
+    # InvalidLinkedSession	251	Error code indicating that a user with a linked (e.g. Facebook) account has an invalid session.
+    # UnsupportedService	252	Error code indicating that a service being linked (e.g. Facebook or Twitter) is unsupported.
+  end
+
 end

data/lib/parse/client/request.rb

@@ -5,52 +5,81 @@ require 'active_support'
 require 'active_support/json'
 
 module Parse
- #This class is mainly to create a potential request - mainly for the batching API.
-
+  #This class represents a Parse request.
   class Request
-      attr_accessor :method, :path, :body, :headers, :opts, :cache
-      attr_accessor :tag #for tracking in bulk requests
-      def initialize(method, uri, body: nil, headers: nil, opts: {})
-        @tag = 0
-        method = method.downcase.to_sym
-        unless method == :get || method == :put || method == :post || method == :delete
-          raise ArgumentError, "Invalid method #{method} for request : '#{uri}'"
-        end
-        self.method = method
-        self.path = uri
-        self.body = body
-        self.headers = headers || {}
-        self.opts = opts || {}
-      end
+    # @!attribute [rw] method
+    #   @return [String] the HTTP method used for this request.
 
+    # @!attribute [rw] path
+    #   @return [String] the uri path.
 
-      def query
-        body if @method == :get
-      end
+    # @!attribute [rw] body
+    #   @return [Hash] the body of this request.
 
-      def as_json
-        signature.as_json
-      end
+    # TODO: Document opts and cache options.
 
-      def ==(r)
-        return false unless r.is_a?(Request)
-        @method == r.method && @path == r.uri && @body == r.body && @headers == r.headers
-      end
+    # @!attribute [rw] opts
+    #   @return [Hash] a set of options for this request.
+    # @!attribute [rw] cache
+    #   @return [Boolean]
+    attr_accessor :method, :path, :body, :headers, :opts, :cache
 
-      # signature provies a way for us to compare different requests objects.
-      # Two requests objects are the same if they have the same signature.
-      # This also helps us serialize a request data into a hash.
-      def signature
-        {method: @method.upcase, path: @path, body: @body}
-      end
+    # @!visibility private
+    # Used to correlate batching requests with their responses.
+    attr_accessor :tag
 
-      def inspect
-          "#<#{self.class} @method=#{@method} @path='#{@path}'>"
+    # Creates a new request
+    # @param method [String] the HTTP method
+    # @param uri [String] the API path of the request (without the host)
+    # @param body [Hash] the body (or parameters) of this request.
+    # @param headers [Hash] additional headers to send in this request.
+    # @param opts [Hash] additional optional parameters.
+    def initialize(method, uri, body: nil, headers: nil, opts: {})
+      @tag = 0
+      method = method.downcase.to_sym
+      unless method == :get || method == :put || method == :post || method == :delete
+        raise ArgumentError, "Invalid method #{method} for request : '#{uri}'"
       end
+      self.method = method
+      self.path = uri
+      self.body = body
+      self.headers = headers || {}
+      self.opts = opts || {}
+    end
 
-      def to_s
-        "#{@method.to_s.upcase} #{@path}"
-      end
+    # The parameters of this request if the HTTP method is GET.
+    # @return [Hash]
+    def query
+      body if @method == :get
+    end
+
+    # @return [Hash] JSON encoded hash
+    def as_json
+      signature.as_json
+    end
+
+    # @return [Boolean]
+    def ==(r)
+      return false unless r.is_a?(Request)
+      @method == r.method && @path == r.uri && @body == r.body && @headers == r.headers
+    end
+
+    # Signature provies a way for us to compare different requests objects.
+    # Two requests objects are the same if they have the same signature.
+    # @return [Hash] A hash representing this request.
+    def signature
+      {method: @method.upcase, path: @path, body: @body}
+    end
+
+    # @!visibility private
+    def inspect
+        "#<#{self.class} @method=#{@method} @path='#{@path}'>"
+    end
+
+    # @return [String]
+    def to_s
+      "#{@method.to_s.upcase} #{@path}"
+    end
 
   end
 

data/lib/parse/client/response.rb

@@ -53,7 +53,7 @@ require 'active_support/json'
 # be a set of responses (from a Batch response).
 module Parse
 
-
+  class ResponseError < StandardError; end;
   class Response
     include Enumerable
 
@@ -66,18 +66,36 @@ module Parse
     ERROR_PASSWORD_MISSING = 201
     ERROR_USERNAME_TAKEN = 202
     ERROR_EMAIL_TAKEN = 203
+    ERROR_EMAIL_NOT_FOUND = 205
+    ERROR_EMAIL_INVALID = 125
 
     ERROR = "error"
     CODE = "code"
     RESULTS = "results"
     COUNT = "count"
-    # A response has a result or (a code and an error)
-    attr_accessor :parse_class, :code, :error, :result, :http_status
-    attr_accessor :request # capture request that created result
+
+    # @!attribute [rw] parse_class
+    #  @return [String] the Parse class for this request
+    # @!attribute [rw] code
+    #  @return [Integer] the error code
+    # @!attribute [rw] error
+    #  @return [Integer] the error message
+    # @!attribute [rw] result
+    #  @return [Hash] the body of the response result.
+    # @!attribute [rw] http_status
+    #  @return [Integer] the HTTP status code from the response.
+    # @!attribute [rw] request
+    #  @return [Integer] the Parse::Request that generated this response.
+    #  @see Parse::Request
+    attr_accessor :parse_class, :code, :error, :result, :http_status,
+                  :request
     # You can query Parse for counting objects, which may not actually have
     # results.
+    # @return [Integer] the count result from a count query request.
     attr_reader :count
 
+    # Create an instance with a Parse response JSON hash.
+    # @param res [Hash] the JSON hash
     def initialize(res = {})
       @http_status = 0
       @count = 0
@@ -86,7 +104,7 @@ module Parse
       # If a string is used for initializing, treat it as JSON
       res = JSON.parse(res) if res.is_a?(String)
       # If it is a hash (or parsed JSON), then parse the result.
-      parse_result(res) if res.is_a?(Hash)
+      parse_result!(res) if res.is_a?(Hash)
       # if the result is an Array, then most likely it is a set of responses
       # from using a Batch API.
       if res.is_a?(Array)
@@ -99,21 +117,14 @@ module Parse
 
     end
 
+    # true if this was a batch response.
     def batch?
       @batch_response
     end
-    #batch response
-    #
-    # [
-    #   {
-    #     "success":{"createdAt":"2015-11-22T19:04:16.104Z","objectId":"s4tEzOVQFc"}
-    #   },
-    #  {
-    #  "error":{"code":101,"error":"object not found for update"}
-    #  }
-    # ]
+
     # If it is a batch respnose, we'll create an array of Response objects for each
     # of the ones in the batch.
+    # @return [Array] an array of Response objects.
     def batch_responses
 
       return [@result] unless @batch_response
@@ -128,8 +139,7 @@ module Parse
     # This method takes the result hash and determines if it is a regular
     # parse query result, object result or a count result. The response should
     # be a hash either containing the result data or the error.
-
-    def parse_result(h)
+    def parse_result!(h)
       @result = {}
       return unless h.is_a?(Hash)
       @code = h[CODE]
@@ -143,31 +153,38 @@ module Parse
       end
 
     end
+    alias_method :parse_results!, :parse_result!
 
-    # determines if the response is successful.
+    # true if the response is successful.
+    # @see #error?
     def success?
       @code.nil? && @error.nil?
     end
 
+    # true if the response has an error code.
+    # @see #success?
     def error?
       ! success?
     end
 
+    # true if the response has an error code of 'object not found'
+    # @see ERROR_OBJECT_NOT_FOUND
     def object_not_found?
       @code == ERROR_OBJECT_NOT_FOUND
     end
 
-    # returns the result data from the response. Always returns an array.
+    # @return [Array] the result data from the response.
     def results
       return [] if @result.nil?
       @result.is_a?(Array) ? @result : [@result]
     end
 
-    # returns the first thing in the array.
+    # @return [Object] the first thing in the result array.
     def first
       @result.is_a?(Array) ? @result.first : @result
     end
-
+    # Iterate through each result item.
+    # @yieldparam [Object] a result entry.
     def each
       return enum_for(:each) unless block_given?
       results.each(&Proc.new)
@@ -182,6 +199,7 @@ module Parse
       end
     end
 
+    # @return [String] JSON encoded object, or an error string.
     def to_s
       return "[E-#{@code}] #{@request} : #{@error} (#{@http_status})" if error?
       @result.to_json

data/lib/parse/model/acl.rb

@@ -12,9 +12,9 @@
 # JSON structure.
 # The class below also implements a type of delegate pattern in order to inform the main Parse::Object
 # of dirty tracking.
+
 module Parse
 
-  # Base class for supporting custom data types
   class DataType
     include ::ActiveModel::Model
     include ::ActiveModel::Serializers::JSON
@@ -33,12 +33,10 @@ module Parse
   end
 
   class ACL < DataType
-    # The internal permissions hash and delegate accessors
+
     attr_accessor :permissions, :delegate
-    PUBLIC = "*" # Public priviledges are '*' key in Parse
+    PUBLIC = "*"
 
-    # provide a set of acls and the delegate (for dirty tracking)
-    # { '*' => { "read": true, "write": true } }
     def initialize(acls = {}, owner: nil)
       everyone(true, true) # sets Public read/write
       @delegate = owner
@@ -48,7 +46,6 @@ module Parse
 
     end
 
-    # helper
     def self.permission(read, write = nil)
         ACL::Permission.new(read, write)
     end
@@ -63,15 +60,13 @@ module Parse
       permissions.keys.all? { |per| permissions[per] == other_acl.permissions[per] }
     end
 
-    # method to set the Public read/write priviledges ('*'). Alias is 'world'
     def everyone(read, write)
       apply(PUBLIC, read, write)
       permissions[PUBLIC]
     end
     alias_method :world, :everyone
 
-    # dirty tracking. We will tell the delegate through the acl_will_change!
-    # method
+    # dirty tracking. We will tell the delegate through the acl_will_change! method
     def will_change!
       @delegate.acl_will_change! if @delegate.respond_to?(:acl_will_change!)
     end

data/lib/parse/model/associations/belongs_to.rb

@@ -6,20 +6,111 @@ require_relative 'collection_proxy'
 require_relative 'pointer_collection_proxy'
 require_relative 'relation_collection_proxy'
 
-# BelongsTo relation is the simplies association in which the local
-# table constains a column that points to a foreign table record using
-# a given Parse Pointer. The key of the property is implied to be the
-# name of the class/parse table that contains the foreign associated record.
-# All belongs to relationship column types have the special data type of :pointer.
+
 module Parse
   module Associations
-
+    # This association creates a one-to-one association with another Parse model.
+    # BelongsTo relation is the simplies association in which the local
+    # Parse table constains a column that has a Parse::Pointer to a foreign table record.
+    #
+    # This association says that this class contains a foreign pointer column
+    # which references a different class. Utilizing the `belongs_to` method in
+    # defining a property in a Parse::Object subclass sets up an association
+    # between the local table and a foreign table. Specifying the `belongs_to`
+    # in the class, tells the framework that the Parse table contains a local
+    # column in its schema that has a reference to a record in a foreign table.
+    # The argument to `belongs_to` should be the singularized version of the
+    # foreign Parse::Object class. you should specify the foreign table as the
+    # snake_case singularized version of the foreign table class.
+    #
+    # Note that the reverse relationship on the foreign class is not generated automatically.
+    # You can use a `has_one` on the foreign model to create it.
+    # @example
+    #  class Author < Parse::Object
+    #  	property :name
+    #  end
+    #
+    #
+    #  class Post < Parse::Object
+    #  	belongs_to :author
+    #  end
+    #
+    #  Post.references # => {:author=>"Author"}
+    #
+    #  post = Post.first
+    #  post.author? # => true if has a pointer
+    #
+    #  # Follow the author pointer and get name
+    #  post.author.name
+    #
+    #  other_author = Author.first
+    #  # change author by setting new pointer
+    #  post.author = other_author
+    #  post.save
+    #
+    # @see Parse::Associations::HasOne
+    # @see Parse::Associations::HasMany
     module BelongsTo
 
+      # @!attribute [rw] self.references
+      #  A hash mapping of all belongs_to associations for this model.
+      #  @return [Hash]
+
+      # @!method key?
+      # A dynamically generated method based on the value of `key` passed to the
+      # belongs_to method, which returns true if this instance has a pointer for
+      # this field.
+      # @example
+      #
+      #  class Post < Parse::Object
+      #  	belongs_to :author # generates 'author?'
+      #  end
+      #
+      #  post = Post.new
+      #  post.author? # => false
+      #  post.author = Author.new
+      #  post.author? # => true
+      # @return [Boolean] true if field contains a Parse::Pointer or subclass.
+
+
+      # @!method self.belongs_to(key, opts = {})
+      # Creates a one-to-one association with another Parse model.
+      # @param [Symbol] key The singularized version of the foreign class and the name of the
+      #   local column in the remote Parse table where the pointer is stored.
+      # @option opts [Symbol] :field override the name of the remote column
+      #  where the pointer is stored. By default this is inferred as
+      #  the columnized of the key parameter.
+      # @option opts [Symbol] :as override the inferred Parse::Object subclass.
+      #  By default this is inferred as the singularized camel case version of
+      #  the key parameter. This option allows you to override the typecast of
+      #  foreign Parse model of the association, while allowing you to have a
+      #  different accessor name.
+      # @option opts [Boolean] :required Setting to `true`, automatically creates
+      #   an ActiveModel validation of `validates_presence_of` for the
+      #   association. This will not prevent the save, but affects the validation
+      #   check when `valid?` is called on an instance. Default is false.
+      # @example
+      #  # Assumes 'Artist' is foreign class.
+      #  belongs_to :artist
+      #
+      #  # uses Parse::User as foreign class
+      #  belongs_to :manager, as: :user
+      #
+      #  # sets attribute name to `featured_song` for foreign class Song with the remote
+      #  # column name in Parse as 'theFeaturedSong'.
+      #  belongs_to :featured_song, as: :song, field: :theFeaturedSong
+      #
+      # @see String#columnize
+      # @see #key?
+      # @return [Parse::Object] a Parse::Object subclass when using the accessor
+      #  when fetching the association.
+
+      # @!visibility private
       def self.included(base)
         base.extend(ClassMethods)
       end
 
+      # @!visibility private
       module ClassMethods
         attr_accessor :references
         # We can keep references to all "belong_to" properties
@@ -27,9 +118,6 @@ module Parse
           @references ||= {}
         end
 
-        # belongs_to :featured_song, as: :song, field: :featuredSong, through: :reference
-        # belongs_to :artist
-        # belongs_to :manager, as: :user
         # These items are added as attributes with the special data type of :pointer
         def belongs_to(key, opts = {})
           opts = {as: key, field: key.to_s.camelize(:lower), required: false}.merge(opts)