/**
 * 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 Chats API provides methods for sending chat messages from one user to another user, or to a group of users called a chat group.
 * The REST object of this class contains the following fields:<ul>
 * <li>chatgroup (NSDictionary): The chat group that the chat belongs to.</li>
 * <li>created_at (NSString): Creation date for this user object.</li>
 * <li>custom_fields (NSString/NSDictionary): User defined fields. </li>
 * <li>id (NSString): Generated unique ID for this chat message.</li>
 * <li>message (NSString): Chat message.</li>
 * <li>photo (APSPhotos): New photo to attach to the chat message.</li>
 * <li>updated_at (NSString): Last update time for this user object.</li>
 * </ul>
 * For more details about the underlying REST object, see the [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Chats).
 */

@interface APSChats : NSObject




/**
 * Sends a chat message to another user or a group of users. 
 *
 * 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/Chats-method-create).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>to_ids (NSString): Comma separated user IDs of the recipient(s).</li>
 * <li>chat_group_id: Identifies an existing chat group by ID.</li>
 * <li>message (NSString): Message to send.</li>
 * <li>photo (APSPhotos): New photo to attach to the chat message.</li>
 * <li>photo_id (NSString): ID of an existing photo to attach to the chat message.</li>
 * <li>custom_fields (NSString/NSDictionary): User defined fields.</li>
 * <li>channel (NSString): Channel for a push notification.</li>
 * <li>payload (NSString/NSDictionary): Message payload for push notification.</li>
 * <li>user_id (NSString): Send on behalf of the identified user.</li>
 * <li>response_json_depth: By default, the chat group with participate users' info will be included in the JSON output.</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>chats (APSChats[]): Single-element array containing the new chat message.</li>
 * </ul>
 */

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


/**
 * Sends a chat message to another user or a group of users. 
 *
 * 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/Chats-method-create).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>to_ids (NSString): Comma separated user IDs of the recipient(s).</li>
 * <li>chat_group_id: Identifies an existing chat group by ID.</li>
 * <li>message (NSString): Message to send.</li>
 * <li>photo (APSPhotos): New photo to attach to the chat message.</li>
 * <li>photo_id (NSString): ID of an existing photo to attach to the chat message.</li>
 * <li>custom_fields (NSString/NSDictionary): User defined fields.</li>
 * <li>channel (NSString): Channel for a push notification.</li>
 * <li>payload (NSString/NSDictionary): Message payload for push notification.</li>
 * <li>user_id (NSString): Send on behalf of the identified user.</li>
 * <li>response_json_depth: By default, the chat group with participate users' info will be included in the JSON output.</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>chats (APSChats[]): Single-element array containing the new chat message.</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;




/**
 * Performs a custom query of chat messages with sorting and pagination. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Chats-method-query).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>participate_ids (NSString): Comma-separated list of user ID(s) of the users belonging to a chat group.</li>
 * <li>chat_group_id: A chat group's id.</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>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>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>chats (APSChats[]): List of chat objects matching the query.</li>
 * </ul>
 */

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




/**
 * Deletes a chat message. 
 *
 * 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/Chats-method-delete).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>chat_id (NSString): ID of the chat message to delete.</li>
 * <li>user_id: User to delete the Chat object on behalf of.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

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




/**
 * Queries chat groups. 
 *
 * 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/Chats-method-query_chat_groups).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>participate_ids: Only available for application admins.</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>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>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>chats (APSChats[]): List of chat objects matching the query.</li>
 * </ul>
 */

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




/**
 * Lists chat groups. 
 *
 * 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/Chats-method-get_chat_groups).
 * @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>where (NSString): Constraint values for fields.</li>
 * <li>order (NSString): Sort results by one or more fields.</li>
 * <li>response_json_depth (NSNumber): Nested object depth level counts in JSON response.</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>chat_groups (NSDictionary[]): List of chat groups.</li>
 * </ul>
 */

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



@end