/**
 * 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 Messages APIs provides methods for sending private messages between users.
 * The REST object of this class contains the following fields:<ul>
 * <li>body (NSString): Message body.</li>
 * <li>created_at (NSString): Message creation date.</li>
 * <li>from (APSUsers): Message sender.</li>
 * <li>id (NSString): ID of the sent message.</li>
 * <li>status (NSString): Status of the message: in-box messages have status of read, unread, or replied.</li>
 * <li>subject (NSString): Message subject.</li>
 * <li>thread_id (NSString): Thread ID of the sent message.</li>
 * <li>to (APSUsers[]): Message recipients.</li>
 * <li>updated_at (NSString): Message update date.</li>
 * </ul>
 * For more details about the underlying REST object, see the [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/Messages).
 */

@interface APSMessages : NSObject




/**
 * Sends a message with an optional subject to one or more specified 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/Messages-method-create).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>to_ids (NSString): Comma-separated list of one or more IDs of users to send the message to. (required)</li>
 * <li>body (NSString): The body of the message . (required)</li>
 * <li>subject (NSString): Message subject.</li>
 * <li>custom_fields (NSString): User-defined data.</li>
 * <li>user_id (NSString): User ID to send message on behalf of.</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>messages (APSMessages[]): A copy of the message as sent.</li>
 * </ul>
 */

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




/**
 * Replies to all recipients of the given message id. 
 *
 * 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/Messages-method-reply).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>message_id: ID of the message to reply to.</li>
 * <li>body: Reply message body text.</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>messages (APSMessages[]): An array containing a single message, the sent message.</li>
 * </ul>
 */

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




/**
 * Shows a message in the user's mailbox. 
 *
 * 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/Messages-method-show).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>message_id (NSString): ID of the message. (required)</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>messages (APSMessages[]): An array with one message item.</li>
 * </ul>
 */

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




/**
 * Shows messages in the current user's inbox. 
 *
 * 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/Messages-method-show_inbox).
 * @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>
 * </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>messages (APSMessages[]): List of inbox messages.</li>
 * </ul>
 */

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




/**
 * Shows messages in the current user's sent messages. 
 *
 * 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/Messages-method-show_sent).
 * @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>
 * </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>messages (APSMessages[]): List of sent  messages.</li>
 * </ul>
 */

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




/**
 * Shows the first message in each of the most recent threads in the user's inbox. 
 *
 * 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/Messages-method-show_threads).
 * @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>
 * </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>messages (APSMessages[]): List of messages representing the first message in each of the user's recent threads.</li>
 * </ul>
 */

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




/**
 * Show messages with the given thread_id from the user's inbox. 
 *
 * 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/Messages-method-show_thread).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>thread_id (NSString): ID of the thread to show messages from.</li>
 * <li>page (NSNumber): Request page number, default is 1.</li>
 * <li>per_page (NSNumber): Number of results per page, default is 10.</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>messages (APSMessages[]): List of messages in the thread.</li>
 * </ul>
 */

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




/**
 * Delete the message with the given id. 
 *
 * 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/Messages-method-delete).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>message_id (NSString): ID of the message to delete.</li>
 * <li>user_id (NSString): User to delete the Message 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;




/**
 * Delete all messages in a thread with the given thread_id. 
 *
 * 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/Messages-method-delete_thread).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>thread_id (NSString): Thread ID of the message thread to delete.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

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



@end