/**
 * 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 Push Notifications API lets you send push notifications to your users who are on iOS and Android Devices.
 * For more details about the underlying REST object, see the [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/PushNotifications).
 */

@interface APSPushNotifications : NSObject




/**
 * Subscribes a mobile device to a push notifications channel. 
 *
 * 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/PushNotifications-method-subscribe).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>channel (NSString): Push notification channel to subscribe to. (required)</li>
 * <li>device_token (NSString): Apple or Android Device Token. (required)</li>
 * <li>user_id (NSString): User ID to subscribe on behalf of.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

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




/**
 * Unsubscribes one of the current user's devices from a push notification channel. 
 *
 * 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/PushNotifications-method-unsubscribe).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>channel (NSString): Name of the push notification channel.</li>
 * <li>device_token (NSString): Apple or Android Device Token. (required)</li>
 * <li>user_id: User ID to unsubscribe from push notifications.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

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




/**
 * Sends push notifications to one or more users who are subscribed to a channel. 
 *
 * 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/PushNotifications-method-notify).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>channel (NSString): Name of the channel. (required)</li>
 * <li>friends (Any): If this parameter is specified (regardless of the parameter's value), push notifications are sent to any of the user's Friends who are subscribed to the identified channel.</li>
 * <li>to_ids (NSString): Comma-separated list of user IDs to send the notification to users who are subscribed to the specified channel.</li>
 * <li>payload (NSString/NSDictionary): Payload to send with the push notification. (required)</li>
 * <li>options (NSDictionary): Additional push options.</li>
 * <li>where (NSDictionary): A JSON-encoded object that defines either the user or location query used to select the device that will receive the notification.</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>push_notification (NSDictionary): Information about the requested push notification:   id: The ID of the requested push notification.</li>
 * </ul>
 */

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




/**
 * Custom query of push notification subscriptions with paginating. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/PushNotifications-method-query).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>user_id (NSString): User ID of the user who has subscribed devices for push notification. (required)</li>
 * <li>channel (NSString): Name of the push notification channel.</li>
 * <li>device_token (NSString): Apple or Android Device Token.</li>
 * <li>type (NSString): Selects the push type.</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>subscriptions (NSDictionary[]): Array of subscription objects, where each subscription object has the following properties:   id : String.</li>
 * </ul>
 */

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




/**
 * Subscribes a mobile device to a push notifications channel. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/PushNotifications-method-subscribe_token).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>device_token (NSString): Android or iOS device token. (required)</li>
 * <li>channel (NSString): Name of the channel. (required)</li>
 * <li>type (NSString): Selects the push type.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

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




/**
 * Unsubscribes the specified device from a push notification channel. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/PushNotifications-method-unsubscribe_token).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>channel (NSString): Name of the push notification channel.</li>
 * <li>device_token (NSString): Android or iOS device token. (required)</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

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




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




/**
 * Sends push notifications to one or more users who are subscribed to a channel. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/PushNotifications-method-notify_tokens).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>channel (NSString): Name of the channel. (required)</li>
 * <li>to_tokens (NSString): Comma-separated list of device tokens. (required)</li>
 * <li>payload (NSString/NSDictionary): Payload to send with the push notification. (required)</li>
 * <li>options (NSDictionary): Additional push options.</li>
 * <li>where (NSDictionary): A JSON-encoded object that defines either the user or location query used to select the device that will receive the notification.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

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




/**
 * Sets the internally stored value of the badge to zero of a specific device. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/PushNotifications-method-reset_badge_put).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>device_token (NSString): Device token. (required)</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

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




/**
 * Sets the value of the internally stored value of the badge. 
 *
 * For more details about the underlying REST method, see the
 * [ACS API Docs](http://docs.appcelerator.com/cloud/latest/#!/api/PushNotifications-method-set_badge).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>device_token (NSString): Device token.</li>
 * <li>badge_number (NSString): Number to set as the badge on the application's icon.</li>
 * </ul>
 * @param handler Callback to handle the server response. See the Callback section in APSClient.
 */

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




/**
 * Returns a list of push notification channels the user is subscribed to. 
 *
 * 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/PushNotifications-method-channels_query).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>user_id (NSString): User to retrieve subscribed channels for.</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>push_channels (NSString[]): List of subscribed channels.</li>
 * </ul>
 */

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




/**
 * Returns the number of devices subscribed to the specified channel. 
 *
 * 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/PushNotifications-method-channels_show).
 * @param data Method parameters specified as an NSDictionary with the following key-value pairs:<ul> 
 * <li>name (NSString): Name of the push channel. (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>devices (NSDictionary): Number of devices subscribed to the channel.</li>
 * </ul>
 */

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



@end