/**
 * Appcelerator Platform SDK
 * Copyright (c) 2014 by Appcelerator, Inc. All Rights Reserved.
 * Proprietary and Confidential - This source code is not for redistribution
 */

#import <Foundation/Foundation.h>
#import "APSCloud.h"


/**
 * Represents a user account.
 * The REST object of this class contains the following fields:<ul>
 * <li>created_at (NSString): Creation date for this user object.</li>
 * <li>custom_fields (NSString/NSDictionary): User defined fields. </li>
 * <li>email (NSString): User's email address. </li>
 * <li>external_accounts (NSDictionary[]): List of external accounts associated with this user. </li>
 * <li>first_name (NSString): User's first name.</li>
 * <li>id (NSString): User's ID, generated by APS.</li>
 * <li>last_name (NSString): User's last name .</li>
 * <li>photo (APSPhotos): Primary photo for this user.</li>
 * <li>role (NSString): User's role.</li>
 * <li>updated_at (NSString): Last update time for this user object.</li>
 * <li>username (NSString): User's login name.</li>
 * </ul>
 * For more details about the underlying REST object, see the [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Users).
 */

@interface APSUsers : NSObject




/**
 * Creates a new user. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Users-method-create).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>email (NSString): User's email address.</li>
 * <li>username (NSString): User's login name.</li>
 * <li>password (NSString): User's password. (required)</li>
 * <li>password_confirmation (NSString): Copy of user's password for confirmation. (required)</li>
 * <li>first_name (NSString): User's first name.</li>
 * <li>last_name (NSString): User's last name.</li>
 * <li>photo (APSPhotos): New photo to attach as the primary photo for the user.</li>
 * <li>photo_id (NSString): ID of an existing photo to attach as the primary photo for the user.</li>
 * <li>tags (NSString): Comma separated list of tags for this user.</li>
 * <li>custom_fields (NSString/NSDictionary): User defined fields.</li>
 * <li>acl_name (NSString): Name of an ACLs to associate with this object.</li>
 * <li>acl_id (NSString): ID of an ACLs to associate with this object.</li>
 * <li>role (NSString): String representation of user role, for example, "teacher".</li>
 * <li>template (NSString): Send a congratulation email to notify that the user has been created successfully.</li>
 * <li>confirmation_template (NSString): If "New User Email Verification" is enabled for the application, APS sends a confirmation email to the user.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 * The response data returns the following method-specific properties:<ul>
 * <li>users (APSUsers[]): Single-element array containing user record for the new user.</li>
 * </ul>
 */

+ (void)create:(NSDictionary *)data withBlock:(APSResponseHandler)handler;


/**
 * Creates a new user. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Users-method-create).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>email (NSString): User's email address.</li>
 * <li>username (NSString): User's login name.</li>
 * <li>password (NSString): User's password. (required)</li>
 * <li>password_confirmation (NSString): Copy of user's password for confirmation. (required)</li>
 * <li>first_name (NSString): User's first name.</li>
 * <li>last_name (NSString): User's last name.</li>
 * <li>photo (APSPhotos): New photo to attach as the primary photo for the user.</li>
 * <li>photo_id (NSString): ID of an existing photo to attach as the primary photo for the user.</li>
 * <li>tags (NSString): Comma separated list of tags for this user.</li>
 * <li>custom_fields (NSString/NSDictionary): User defined fields.</li>
 * <li>acl_name (NSString): Name of an ACLs to associate with this object.</li>
 * <li>acl_id (NSString): ID of an ACLs to associate with this object.</li>
 * <li>role (NSString): String representation of user role, for example, "teacher".</li>
 * <li>template (NSString): Send a congratulation email to notify that the user has been created successfully.</li>
 * <li>confirmation_template (NSString): If "New User Email Verification" is enabled for the application, APS sends a confirmation email to the user.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 * The response data returns the following method-specific properties:<ul>
 * <li>users (APSUsers[]): Single-element array containing user record for the new user.</li>
 * </ul>
 * @param progressHandler Callback to handle the progress of the request. See the Callback section in APSClient.
 */

+ (void)create:(NSDictionary *)data withBlock:(APSResponseHandler)handler progressBlock:(APSProgressHandler)progressHandler;




/**
 * Log a user in using their ACS credentials. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Users-method-login).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>login (NSString): Email address or username of the user to login.</li>
 * <li>password (NSString): User's password.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

+ (void)login:(NSDictionary *)data withBlock:(APSResponseHandler)handler;




/**
 * Shows public user information. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Users-method-show).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>user_id (NSString): User ID of the user to show.</li>
 * <li>user_ids (NSString): Comma-separated list of user IDs to show.</li>
 * <li>response_json_depth (NSNumber): Nested object depth level counts in response json.</li>
 * <li>show_user_like (NSBoolean): If set to true the User object in the response will include "current_user_liked: true" if the current user has liked the object.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 * The response data returns the following method-specific properties:<ul>
 * <li>users (APSUsers[]): List of user profiles.</li>
 * </ul>
 */

+ (void)show:(NSDictionary *)data withBlock:(APSResponseHandler)handler;




/**
 * Shows both public and private user information about the user who is currently logged in. 
 *
 * To use this method, **a user must be logged in before calling this method.**
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Users-method-show_me).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>response_json_depth (NSNumber): Nested object depth level counts in response json.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

+ (void)showMe:(NSDictionary *)data withBlock:(APSResponseHandler)handler;




/**
 * Returns the list of users that have been added to the app, sorted by search relevancy. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Users-method-search).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>page (NSNumber): Request page number, default is 1.</li>
 * <li>per_page (NSNumber): Number of results per page, default is 10.</li>
 * <li>q: Space-separated list of keywords, used to perform full text search on first name, last name, email address, username and tags fields.</li>
 * <li>response_json_depth: Nested object depth level counts in response json.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

+ (void)search:(NSDictionary *)data withBlock:(APSResponseHandler)handler;




/**
 * Custom query of Users objects with sorting and paginating. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Users-method-query).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>page (NSNumber): Request page number, default is 1.</li>
 * <li>per_page (NSNumber): Number of results per page, default is 10.</li>
 * <li>limit (NSNumber): Instead of using page and per_page for pagination, you can use limit and skip to do your own pagination.</li>
 * <li>skip (NSNumber): Number of records to skip.</li>
 * <li>where (NSDictionary): Constraint values for fields.</li>
 * <li>order (NSString): Sort results by one or more fields.</li>
 * <li>sel (NSDictionary): Selects the object fields to display.</li>
 * <li>show_user_like (NSBoolean): If set to true, each User object in the response includes "current_user_liked: true"  if the current user has liked the object.</li>
 * <li>unsel (NSDictionary): Selects the object fields NOT to display.</li>
 * <li>response_json_depth (NSNumber): Nested object depth level counts in response json.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 * The response data returns the following method-specific properties:<ul>
 * <li>users (APSUsers[]): List of users matching the query parameters.</li>
 * </ul>
 */

+ (void)query:(NSDictionary *)data withBlock:(APSResponseHandler)handler;




/**
 * Any of the same parameters as create can be used to update the current user. 
 *
 * To use this method, **a user must be logged in before calling this method.**
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Users-method-update).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>email (NSString): Email address.</li>
 * <li>username (NSString): User name.</li>
 * <li>password (NSString): Password.</li>
 * <li>password_confirmation (NSString): Password.</li>
 * <li>first_name (NSString): First name.</li>
 * <li>last_name (NSString): First name.</li>
 * <li>photo (APSPhotos): New photo to assign as the user's primary photo.</li>
 * <li>photo_id (NSString): ID of an existing photo to use as the user's primary photo.</li>
 * <li>tags (NSString): Comma separated tags, overwrites the existing tags.</li>
 * <li>custom data fields (NSString): User-defined data.</li>
 * <li>acl_name (NSString): Name of an ACLs to associate with this object.</li>
 * <li>acl_id (NSString): ID of an ACLs to associate with this object.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 * The response data returns the following method-specific properties:<ul>
 * <li>users (APSUsers[]): Single-element array containing the updated user object.</li>
 * </ul>
 */

+ (void)update:(NSDictionary *)data withBlock:(APSResponseHandler)handler;


/**
 * Any of the same parameters as create can be used to update the current user. 
 *
 * To use this method, **a user must be logged in before calling this method.**
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Users-method-update).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>email (NSString): Email address.</li>
 * <li>username (NSString): User name.</li>
 * <li>password (NSString): Password.</li>
 * <li>password_confirmation (NSString): Password.</li>
 * <li>first_name (NSString): First name.</li>
 * <li>last_name (NSString): First name.</li>
 * <li>photo (APSPhotos): New photo to assign as the user's primary photo.</li>
 * <li>photo_id (NSString): ID of an existing photo to use as the user's primary photo.</li>
 * <li>tags (NSString): Comma separated tags, overwrites the existing tags.</li>
 * <li>custom data fields (NSString): User-defined data.</li>
 * <li>acl_name (NSString): Name of an ACLs to associate with this object.</li>
 * <li>acl_id (NSString): ID of an ACLs to associate with this object.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 * The response data returns the following method-specific properties:<ul>
 * <li>users (APSUsers[]): Single-element array containing the updated user object.</li>
 * </ul>
 * @param progressHandler Callback to handle the progress of the request. See the Callback section in APSClient.
 */

+ (void)update:(NSDictionary *)data withBlock:(APSResponseHandler)handler progressBlock:(APSProgressHandler)progressHandler;




/**
 * Log out a user. 
 *
 * To use this method, **a user must be logged in before calling this method.**
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Users-method-logout).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>device_token: If specified, all push subscriptions associated with this device token are canceled.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

+ (void)logout:(NSDictionary *)data withBlock:(APSResponseHandler)handler;




/**
 * User must already be logged in to his account in order to delete it. 
 *
 * To use this method, **a user must be logged in before calling this method.**
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Users-method-delete).
 * @param data Unused.
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

+ (void)remove:(NSDictionary *)data withBlock:(APSResponseHandler)handler;




/**
 * Send an email to a user to recover lost password. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Users-method-request_reset_password).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>email (NSString): Email address. (required)</li>
 * <li>subject: The default subject of the password reset email is "Password reset request for {{your app name}}".</li>
 * <li>template: If you wish to use your custom email body.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

+ (void)requestResetPassword:(NSDictionary *)data withBlock:(APSResponseHandler)handler;




/**
 * If you enabled new user account email verification in your App settings, all new users will receive an email containi
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Users-method-resend_confirmation).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>email (NSString): Email must match user's registered email. (required)</li>
 * <li>confirmation_subject (NSString): The default subject of the email verification is "Email Verification Instructions for {{your app name}}".</li>
 * <li>confirmation_template: If you wish to use your custom email body.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

+ (void)resendConfirmation:(NSDictionary *)data withBlock:(APSResponseHandler)handler;



@end