/**
 * 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"


/**
 * The Friends API provides methods for managing friendships between the current user and another user.
 * For more details about the underlying REST object, see the [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Friends).
 */

@interface APSFriends : NSObject




/**
 * Add friends to 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/Friends-method-add).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>user_ids: Comma-separated list consisting of IDs of one or more users to add as friends to the current user. (required)</li>
 * <li>approval_required (NSBoolean): Indicates whether the friend request requires approval by the other users.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

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




/**
 * View pending friend requests. 
 *
 * 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/Friends-method-requests).
 * @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.
 * The response data returns the following method-specific properties:<ul>
 * <li>friend_requests (NSDictionary[]): A list of friend requests, where each friend request is an object with the following members:   id: String.</li>
 * </ul>
 */

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




/**
 * Approve an existing friend request. 
 *
 * 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/Friends-method-approve).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>user_ids: Comma-separated list consisting of IDs of one or more users to approve as friends to the current user. (required)</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

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




/**
 * Removes a one or more friends from the user's friends list. 
 *
 * 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/Friends-method-remove).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>user_ids: Comma-separated list consisting of IDs of one or more users to add as friends to the current user. (required)</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

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




/**
 * Search for friends of the current user or a specified 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/Friends-method-search).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>user_id: ID of the user to search for friends.</li>
 * <li>followers: If you have friends set to one way, pass followers=true to query user_id's followers' .</li>
 * <li>q: Space-separated list of keywords used to perform full text search on first name, last name, email address, username and tags.</li>
 * <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>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 search criteria.</li>
 * </ul>
 */

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



@end