Code cleanup and added in documentation (#25)

* Code cleanup and added in documentation

* Code review fixes, changed call signatures for disablePush

* changes and fixes

* use NSNull instead of nil, and check that email and hexToken exist

* only check email if needed

Author: davidtruong

Artifacts/include/Iterable-iOS-SDK/IterableAPI.h

@@ -51,6 +51,10 @@ typedef NS_ENUM(NSInteger, PushServicePlatform) {
  */
 @property(nonatomic, readonly, copy) NSString *email;
 
+/**
+ The hex representation of this device token
+ */
+@property(nonatomic, readonly, copy) NSString *hexToken;
 
 /////////////////////////////////
 /// @name Creating an IterableAPI
@@ -152,6 +156,51 @@ typedef NS_ENUM(NSInteger, PushServicePlatform) {
  */
 - (void)registerToken:(NSData *)token appName:(NSString *)appName pushServicePlatform:(PushServicePlatform)pushServicePlatform onSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure;
 
+/////////////////////////////
+/// @name Disabling a device
+/////////////////////////////
+
+/*!
+ @method
+ 
+ @abstract Disable this device's token in Iterable, for the current user
+ */
+- (void)disableDeviceForCurrentUser;
+
+/*!
+ @method
+ 
+ @abstract Disable this device's token in Iterable, for all users with this device
+  */
+- (void)disableDeviceForAllUsers;
+
+/*!
+ @method
+ 
+ @abstract Disable this device's token in Iterable, for the current user, with custom completion blocks
+ 
+ @param onSuccess               OnSuccessHandler to invoke if disabling the token is successful
+ @param onFailure               OnFailureHandler to invoke if disabling the token fails
+ 
+ @see OnSuccessHandler
+ @see OnFailureHandler
+ */
+- (void)disableDeviceForCurrentUserWithOnSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure;
+
+/*!
+ @method
+ 
+ @abstract Disable this device's token in Iterable, for all users with this device, with custom completion blocks
+ 
+ @param onSuccess               OnSuccessHandler to invoke if disabling the token is successful
+ @param onFailure               OnFailureHandler to invoke if disabling the token fails
+ 
+ @see OnSuccessHandler
+ @see OnFailureHandler
+ */
+- (void)disableDeviceForAllUsersWithOnSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure;
+
+
 /////////////////////////
 /// @name Tracking events
 /////////////////////////

Artifacts/libIterable-iOS-SDK.a

@@ -51,6 +51,10 @@ typedef NS_ENUM(NSInteger, PushServicePlatform) {
  */
 @property(nonatomic, readonly, copy) NSString *email;
 
+/**
+ The hex representation of this device token
+ */
+@property(nonatomic, readonly, copy) NSString *hexToken;
 
 /////////////////////////////////
 /// @name Creating an IterableAPI
@@ -153,10 +157,48 @@ typedef NS_ENUM(NSInteger, PushServicePlatform) {
 - (void)registerToken:(NSData *)token appName:(NSString *)appName pushServicePlatform:(PushServicePlatform)pushServicePlatform onSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure;
 
 /////////////////////////////
-/// @name Disabling a token
+/// @name Disabling a device
 /////////////////////////////
 
-- (void)disableToken:(NSData *)token appName:(NSString *)appName pushServicePlatform:(PushServicePlatform)pushServicePlatform;
+/*!
+ @method
+ 
+ @abstract Disable this device's token in Iterable, for the current user
+ */
+- (void)disableDeviceForCurrentUser;
+
+/*!
+ @method
+ 
+ @abstract Disable this device's token in Iterable, for all users with this device
+  */
+- (void)disableDeviceForAllUsers;
+
+/*!
+ @method
+ 
+ @abstract Disable this device's token in Iterable, for the current user, with custom completion blocks
+ 
+ @param onSuccess               OnSuccessHandler to invoke if disabling the token is successful
+ @param onFailure               OnFailureHandler to invoke if disabling the token fails
+ 
+ @see OnSuccessHandler
+ @see OnFailureHandler
+ */
+- (void)disableDeviceForCurrentUserWithOnSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure;
+
+/*!
+ @method
+ 
+ @abstract Disable this device's token in Iterable, for all users with this device, with custom completion blocks
+ 
+ @param onSuccess               OnSuccessHandler to invoke if disabling the token is successful
+ @param onFailure               OnFailureHandler to invoke if disabling the token fails
+ 
+ @see OnSuccessHandler
+ @see OnFailureHandler
+ */
+- (void)disableDeviceForAllUsersWithOnSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure;
 
 
 /////////////////////////

Iterable-iOS-SDK/IterableAPI.h

@@ -311,6 +311,7 @@ - (void)registerToken:(NSData *)token appName:(NSString *)appName pushServicePla
 - (void)registerToken:(NSData *)token appName:(NSString *)appName pushServicePlatform:(PushServicePlatform)pushServicePlatform onSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure
 {
     NSString *hexToken = [token hexadecimalString];
+    _hexToken = hexToken;
 
     UIDevice *device = [UIDevice currentDevice];
     NSString *psp = [IterableAPI pushServicePlatformToString:pushServicePlatform];
@@ -344,33 +345,58 @@ - (void)registerToken:(NSData *)token appName:(NSString *)appName pushServicePla
     [self sendRequest:request onSuccess:onSuccess onFailure:onFailure];
 }
 
-- (void)disableToken:(NSData *)token appName:(NSString *)appName pushServicePlatform:(PushServicePlatform)pushServicePlatform {
-    NSString *hexToken = [token hexadecimalString];
-    
-    if ([hexToken length] != 64) {
-        NSLog(@"registerToken: invalid token");
-    } else {
-        NSString *psp = [IterableAPI pushServicePlatformToString:pushServicePlatform];
-        
-        if (!psp) {
-            LogError(@"disableToken: invalid pushServicePlatform");
-            return;
+/*!
+ @method
+ 
+ @abstract Disable this device's token in Iterable with custom completion blocks. `allUsers` indicates whether to disable for all users with this token, or only current user 
+ 
+ @param onSuccess               OnSuccessHandler to invoke if disabling the token is successful
+ @param onFailure               OnFailureHandler to invoke if disabling the token fails
+ 
+ @see OnSuccessHandler
+ @see OnFailureHandler
+ */
+- (void)disableDevice:(BOOL)allUsers onSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure
+{
+    if (!self.hexToken || (!allUsers && !self.email)) {
+        LogWarning(@"disableDevice: email or token not yet registered");
+        if (onFailure) {
+            onFailure(@"Not disabling device - you must call registerToken first, and sharedInstance must have an email", [[NSData alloc] init]);
         }
-        
-        NSDictionary *args = @{
-                               @"email": self.email,
-                               @"token": hexToken
-                               };
-        LogDebug(@"sending disableToken request with args %@", args);
-        NSURLRequest *request = [self createRequestForAction:@"users/disableDevice" withArgs:args];
-        [self sendRequest:request onSuccess:^(NSDictionary *data)
-         {
-             LogDebug(@"disable succeeded to send, got data: %@", data);
-         } onFailure:^(NSString *reason, NSData *data)
-         {
-             LogDebug(@"disable failed to send: %@. Got data %@", reason, data);
-         }];
+        return;
     }
+    NSDictionary *args = @{
+                           @"email": allUsers ? [NSNull null]: self.email,
+                           @"token": self.hexToken
+                           };
+    
+    LogDebug(@"sending disableToken request with args %@", args);
+    NSURLRequest *request = [self createRequestForAction:@"users/disableDevice" withArgs:args];
+    [self sendRequest:request onSuccess:onSuccess onFailure:onFailure];
+}
+
+// documented in IterableAPI.h
+- (void)disableDeviceForCurrentUser
+{
+    return [self disableDeviceForCurrentUserWithOnSuccess:[IterableAPI defaultOnSuccess:@"disableDevice"] onFailure:[IterableAPI defaultOnFailure:@"disableDevice"]];
+}
+
+// documented in IterableAPI.h
+- (void)disableDeviceForAllUsers
+{
+    return [self disableDeviceForAllUsersWithOnSuccess:[IterableAPI defaultOnSuccess:@"disableDevice"] onFailure:[IterableAPI defaultOnFailure:@"disableDevice"]];
+}
+
+// documented in IterableAPI.h
+- (void)disableDeviceForCurrentUserWithOnSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure
+{
+    return [self disableDevice:FALSE onSuccess:onSuccess onFailure:onFailure];
+}
+
+// documented in IterableAPI.h
+- (void)disableDeviceForAllUsersWithOnSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure
+{
+    return [self disableDevice:TRUE onSuccess:onSuccess onFailure:onFailure];
 }
 
 // documented in IterableAPI.h