Merge pull request #304 from stripe/jack-additional-params

jack-stripe · jack-stripe · commit 2ff755e209a3 · 2016-02-05T17:47:37.000-05:00
Add additionalFields to STPFormEncodable/STPAPIResponseDecodable
diff --git a/Stripe/PublicHeaders/STPAPIResponseDecodable.h b/Stripe/PublicHeaders/STPAPIResponseDecodable.h
@@ -10,7 +10,19 @@
 
 @protocol STPAPIResponseDecodable <NSObject>
 
+/**
+ * These fields are required to be present in the API response. If any of them are nil, decodedObjectFromAPIResponse should also return nil.
+ */
 + (nonnull NSArray *)requiredFields;
+
+/**
+ * Parses an response from the Stripe API (in JSON format; represented as an NSDictionary) into an instance of the class. Returns nil if the object could not be decoded (i.e. if one of its `requiredFields` is nil).
+ */
 + (nullable instancetype)decodedObjectFromAPIResponse:(nonnull NSDictionary *)response;
 
+/**
+ * The raw JSON response used to create the object. This can be useful for using beta features that haven't yet been made into properties in the SDK.
+ */
+@property(nonatomic, readonly, nonnull, copy)NSDictionary *allResponseFields;
+
 @end
diff --git a/Stripe/PublicHeaders/STPFormEncodable.h b/Stripe/PublicHeaders/STPFormEncodable.h
@@ -8,9 +8,28 @@
 
 #import <Foundation/Foundation.h>
 
+/**
+ * Objects conforming to STPFormEncodable can be automatically converted to a form-encoded string, which can then be used when making requests to the Stripe API.
+ */
 @protocol STPFormEncodable <NSObject>
 
-+ (NSString *)rootObjectName;
-+ (NSDictionary *)propertyNamesToFormFieldNamesMapping;
+/**
+ * The root object name to be used when converting this object to a form-encoded string. For example, if this returns @"card", then the form-encoded output will resemble @"card[foo]=bar" (where 'foo' and 'bar' are specified by `propertyNamesToFormFieldNamesMapping` below.
+ */
++ (nonnull NSString *)rootObjectName;
+
+/**
+ * This maps properties on an object that is being form-encoded into parameter names in the Stripe API. For example, STPCardParams has a field called `expMonth`, but the Stripe API expects a field called `exp_month`. This dictionary represents a mapping from the former to the latter (in other words, [STPCardParams propertyNamesToFormFieldNamesMapping][@"expMonth"] == @"exp_month".)
+ */
++ (nonnull NSDictionary *)propertyNamesToFormFieldNamesMapping;
+
+/**
+ * You can use this property to add additional fields to an API request that are not explicitly defined by the object's interface. This can be useful when using beta features that haven't been added to the Stripe SDK yet. For example, if the /v1/tokens API began to accept a beta field called "test_field", you might do the following:
+    STPCardParams *cardParams = [STPCardParams new];
+    // add card values
+    cardParams.additionalAPIParameters = @{@"test_field": @"example_value"};
+    [[STPAPIClient sharedClient] createTokenWithCard:cardParams completion:...];
+ */
+@property(nonatomic, readwrite, nonnull, copy)NSDictionary *additionalAPIParameters;
 
 @end
diff --git a/Stripe/STPBankAccount.m b/Stripe/STPBankAccount.m
@@ -16,6 +16,7 @@ @interface STPBankAccount ()
 @property (nonatomic, readwrite) NSString *bankName;
 @property (nonatomic, readwrite) NSString *fingerprint;
 @property (nonatomic) STPBankAccountStatus status;
+@property (nonatomic, readwrite, nonnull, copy) NSDictionary *allResponseFields;
 
 @end
 
@@ -90,6 +91,8 @@ + (instancetype)decodedObjectFromAPIResponse:(NSDictionary *)response {
     } else if ([status isEqual: @"errored"]) {
         bankAccount.status = STPBankAccountStatusErrored;
     }
+    
+    bankAccount.allResponseFields = dict;
     return bankAccount;
 }
 
diff --git a/Stripe/STPBankAccountParams.m b/Stripe/STPBankAccountParams.m
@@ -10,6 +10,16 @@
 
 @implementation STPBankAccountParams
 
+@synthesize additionalAPIParameters = _additionalAPIParameters;
+
+- (instancetype)init {
+    self = [super init];
+    if (self) {
+        _additionalAPIParameters = @{};
+    }
+    return self;
+}
+
 - (NSString *)last4 {
     if (self.accountNumber && self.accountNumber.length >= 4) {
         return [self.accountNumber substringFromIndex:(self.accountNumber.length - 4)];
diff --git a/Stripe/STPCard.m b/Stripe/STPCard.m
@@ -20,6 +20,7 @@ @interface STPCard ()
 @property (nonatomic, readwrite) STPCardFundingType funding;
 @property (nonatomic, readwrite) NSString *fingerprint;
 @property (nonatomic, readwrite) NSString *country;
+@property (nonatomic, readwrite, nonnull, copy) NSDictionary *allResponseFields;
 
 @end
 
@@ -135,6 +136,8 @@ + (instancetype)decodedObjectFromAPIResponse:(NSDictionary *)response {
     card.addressState = dict[@"address_state"];
     card.addressZip = dict[@"address_zip"];
     card.addressCountry = dict[@"address_country"];
+    
+    card.allResponseFields = dict;
     return card;
 }
 #pragma clang diagnostic pop
diff --git a/Stripe/STPCardParams.m b/Stripe/STPCardParams.m
@@ -12,6 +12,16 @@
 
 @implementation STPCardParams
 
+@synthesize additionalAPIParameters = _additionalAPIParameters;
+
+- (instancetype)init {
+    self = [super init];
+    if (self) {
+        _additionalAPIParameters = @{};
+    }
+    return self;
+}
+
 - (NSString *)last4 {
     if (self.number && self.number.length >= 4) {
         return [self.number substringFromIndex:(self.number.length - 4)];
diff --git a/Stripe/STPFormEncoder.m b/Stripe/STPFormEncoder.m
@@ -11,49 +11,176 @@
 #import "STPCardParams.h"
 #import "STPFormEncodable.h"
 
+FOUNDATION_EXPORT NSString * STPPercentEscapedStringFromString(NSString *string);
+FOUNDATION_EXPORT NSString * STPQueryStringFromParameters(NSDictionary *parameters);
+
 @implementation STPFormEncoder
 
++ (NSString *)stringByReplacingSnakeCaseWithCamelCase:(NSString *)input {
+    NSArray *parts = [input componentsSeparatedByString:@"_"];
+    NSMutableString *camelCaseParam = [NSMutableString string];
+    [parts enumerateObjectsUsingBlock:^(NSString *part, NSUInteger idx, __unused BOOL *stop) {
+        [camelCaseParam appendString:(idx == 0 ? part : [part capitalizedString])];
+    }];
+    
+    return [camelCaseParam copy];
+}
+
 + (nonnull NSData *)formEncodedDataForObject:(nonnull NSObject<STPFormEncodable> *)object {
-    NSMutableArray *parts = [NSMutableArray array];
+    NSDictionary *dict = @{
+                           [object.class rootObjectName]: [self keyPairDictionaryForObject:object]
+                           };
+    return [STPQueryStringFromParameters(dict) dataUsingEncoding:NSUTF8StringEncoding];
+}
+
++ (NSDictionary *)keyPairDictionaryForObject:(nonnull NSObject<STPFormEncodable> *)object {
+    NSMutableDictionary *keyPairs = [NSMutableDictionary dictionary];
     [[object.class propertyNamesToFormFieldNamesMapping] enumerateKeysAndObjectsUsingBlock:^(NSString * _Nonnull propertyName, NSString *  _Nonnull formFieldName, __unused BOOL * _Nonnull stop) {
-        NSString *formFieldValue = [[object valueForKey:propertyName] description];
-        if (formFieldValue) {
-            [parts addObject:[NSString stringWithFormat:@"%@[%@]=%@", [object.class rootObjectName], formFieldName, [self.class stringByURLEncoding:formFieldValue]]];
+        id value = [self formEncodableValueForObject:[object valueForKey:propertyName]];
+        if (value) {
+            keyPairs[formFieldName] = value;
+        }
+    }];
+    [object.additionalAPIParameters enumerateKeysAndObjectsUsingBlock:^(id  _Nonnull additionalFieldName, id  _Nonnull additionalFieldValue, __unused BOOL * _Nonnull stop) {
+        id value = [self formEncodableValueForObject:additionalFieldValue];
+        if (value) {
+            keyPairs[additionalFieldName] = value;
         }
     }];
-    return [[parts componentsJoinedByString:@"&"] dataUsingEncoding:NSUTF8StringEncoding];
+    return [keyPairs copy];
+}
+
++ (id)formEncodableValueForObject:(NSObject *)object {
+    if ([object conformsToProtocol:@protocol(STPFormEncodable)]) {
+        return [self keyPairDictionaryForObject:(NSObject<STPFormEncodable>*)object];
+    } else {
+        return object;
+    }
 }
 
-/* This code is adapted from the code by David DeLong in this StackOverflow post:
- http://stackoverflow.com/questions/3423545/objective-c-iphone-percent-encode-a-string .  It is protected under the terms of a Creative Commons
- license: http://creativecommons.org/licenses/by-sa/3.0/
- */
 + (NSString *)stringByURLEncoding:(NSString *)string {
-    NSMutableString *output = [NSMutableString string];
-    const unsigned char *source = (const unsigned char *)[string UTF8String];
-    NSInteger sourceLen = strlen((const char *)source);
-    for (int i = 0; i < sourceLen; ++i) {
-        const unsigned char thisChar = source[i];
-        if (thisChar == ' ') {
-            [output appendString:@"+"];
-        } else if (thisChar == '.' || thisChar == '-' || thisChar == '_' || thisChar == '~' || (thisChar >= 'a' && thisChar <= 'z') ||
-                   (thisChar >= 'A' && thisChar <= 'Z') || (thisChar >= '0' && thisChar <= '9')) {
-            [output appendFormat:@"%c", thisChar];
-        } else {
-            [output appendFormat:@"%%%02X", thisChar];
-        }
+    return STPPercentEscapedStringFromString(string);
+}
+
+@end
+
+
+// This code is adapted from https://github.com/AFNetworking/AFNetworking/blob/master/AFNetworking/AFURLRequestSerialization.m . The only modifications are to replace the AF namespace with the STP namespace to avoid collisions with apps that are using both Stripe and AFNetworking.
+NSString * STPPercentEscapedStringFromString(NSString *string) {
+    static NSString * const kSTPCharactersGeneralDelimitersToEncode = @":#[]@"; // does not include "?" or "/" due to RFC 3986 - Section 3.4
+    static NSString * const kSTPCharactersSubDelimitersToEncode = @"!$&'()*+,;=";
+    
+    NSMutableCharacterSet * allowedCharacterSet = [[NSCharacterSet URLQueryAllowedCharacterSet] mutableCopy];
+    [allowedCharacterSet removeCharactersInString:[kSTPCharactersGeneralDelimitersToEncode stringByAppendingString:kSTPCharactersSubDelimitersToEncode]];
+    
+    // FIXME: https://github.com/AFNetworking/AFNetworking/pull/3028
+    // return [string stringByAddingPercentEncodingWithAllowedCharacters:allowedCharacterSet];
+    
+    static NSUInteger const batchSize = 50;
+    
+    NSUInteger index = 0;
+    NSMutableString *escaped = @"".mutableCopy;
+    
+    while (index < string.length) {
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wgnu"
+        NSUInteger length = MIN(string.length - index, batchSize);
+#pragma GCC diagnostic pop
+        NSRange range = NSMakeRange(index, length);
+        
+        // To avoid breaking up character sequences such as 👴🏻👮🏽
+        range = [string rangeOfComposedCharacterSequencesForRange:range];
+        
+        NSString *substring = [string substringWithRange:range];
+        NSString *encoded = [substring stringByAddingPercentEncodingWithAllowedCharacters:allowedCharacterSet];
+        [escaped appendString:encoded];
+        
+        index += range.length;
     }
-    return output;
+    
+    return escaped;
 }
 
-+ (NSString *)stringByReplacingSnakeCaseWithCamelCase:(NSString *)input {
-    NSArray *parts = [input componentsSeparatedByString:@"_"];
-    NSMutableString *camelCaseParam = [NSMutableString string];
-    [parts enumerateObjectsUsingBlock:^(NSString *part, NSUInteger idx, __unused BOOL *stop) {
-        [camelCaseParam appendString:(idx == 0 ? part : [part capitalizedString])];
-    }];
+#pragma mark -
+
+@interface STPQueryStringPair : NSObject
+@property (readwrite, nonatomic, strong) id field;
+@property (readwrite, nonatomic, strong) id value;
+
+- (instancetype)initWithField:(id)field value:(id)value;
+
+- (NSString *)URLEncodedStringValue;
+@end
+
+@implementation STPQueryStringPair
+
+- (instancetype)initWithField:(id)field value:(id)value {
+    self = [super init];
+    if (!self) {
+        return nil;
+    }
     
-    return [camelCaseParam copy];
+    _field = field;
+    _value = value;
+    
+    return self;
+}
+
+- (NSString *)URLEncodedStringValue {
+    if (!self.value || [self.value isEqual:[NSNull null]]) {
+        return STPPercentEscapedStringFromString([self.field description]);
+    } else {
+        return [NSString stringWithFormat:@"%@=%@", STPPercentEscapedStringFromString([self.field description]), STPPercentEscapedStringFromString([self.value description])];
+    }
 }
 
 @end
+
+#pragma mark -
+
+FOUNDATION_EXPORT NSArray * STPQueryStringPairsFromDictionary(NSDictionary *dictionary);
+FOUNDATION_EXPORT NSArray * STPQueryStringPairsFromKeyAndValue(NSString *key, id value);
+
+NSString * STPQueryStringFromParameters(NSDictionary *parameters) {
+    NSMutableArray *mutablePairs = [NSMutableArray array];
+    for (STPQueryStringPair *pair in STPQueryStringPairsFromDictionary(parameters)) {
+        [mutablePairs addObject:[pair URLEncodedStringValue]];
+    }
+    
+    return [mutablePairs componentsJoinedByString:@"&"];
+}
+
+NSArray * STPQueryStringPairsFromDictionary(NSDictionary *dictionary) {
+    return STPQueryStringPairsFromKeyAndValue(nil, dictionary);
+}
+
+NSArray * STPQueryStringPairsFromKeyAndValue(NSString *key, id value) {
+    NSMutableArray *mutableQueryStringComponents = [NSMutableArray array];
+    NSString *descriptionSelector = NSStringFromSelector(@selector(description));
+    NSSortDescriptor *sortDescriptor = [NSSortDescriptor sortDescriptorWithKey:descriptionSelector ascending:YES selector:@selector(compare:)];
+    
+    if ([value isKindOfClass:[NSDictionary class]]) {
+        NSDictionary *dictionary = value;
+        // Sort dictionary keys to ensure consistent ordering in query string, which is important when deserializing potentially ambiguous sequences, such as an array of dictionaries
+        for (id nestedKey in [dictionary.allKeys sortedArrayUsingDescriptors:@[ sortDescriptor ]]) {
+            id nestedValue = dictionary[nestedKey];
+            if (nestedValue) {
+                [mutableQueryStringComponents addObjectsFromArray:STPQueryStringPairsFromKeyAndValue((key ? [NSString stringWithFormat:@"%@[%@]", key, nestedKey] : nestedKey), nestedValue)];
+            }
+        }
+    } else if ([value isKindOfClass:[NSArray class]]) {
+        NSArray *array = value;
+        for (id nestedValue in array) {
+            [mutableQueryStringComponents addObjectsFromArray:STPQueryStringPairsFromKeyAndValue([NSString stringWithFormat:@"%@[]", key], nestedValue)];
+        }
+    } else if ([value isKindOfClass:[NSSet class]]) {
+        NSSet *set = value;
+        for (id obj in [set sortedArrayUsingDescriptors:@[ sortDescriptor ]]) {
+            [mutableQueryStringComponents addObjectsFromArray:STPQueryStringPairsFromKeyAndValue(key, obj)];
+        }
+    } else {
+        [mutableQueryStringComponents addObject:[[STPQueryStringPair alloc] initWithField:key value:value]];
+    }
+    
+    return mutableQueryStringComponents;
+}
diff --git a/Stripe/STPToken.m b/Stripe/STPToken.m
@@ -17,6 +17,7 @@ @interface STPToken()
 @property (nonatomic, nullable) STPCard *card;
 @property (nonatomic, nullable) STPBankAccount *bankAccount;
 @property (nonatomic, nullable) NSDate *created;
+@property (nonatomic, readwrite, nonnull, copy) NSDictionary *allResponseFields;
 @end
 
 @implementation STPToken
@@ -86,6 +87,8 @@ + (instancetype)decodedObjectFromAPIResponse:(NSDictionary *)response {
     if (bankAccountDictionary) {
         token.bankAccount = [STPBankAccount decodedObjectFromAPIResponse:bankAccountDictionary];
     }
+    
+    token.allResponseFields = dict;
     return token;
 }
 
diff --git a/Tests/Tests/STPApplePayTest.m b/Tests/Tests/STPApplePayTest.m
@@ -65,7 +65,7 @@ - (void)testCreateTokenWithPayment {
 
     STPAPIClient *client = [[STPAPIClient alloc] initWithPublishableKey:@"pk_test_vOo1umqsYxSrP5UXfOeL3ecm"];
 
-    XCTestExpectation *expectation = [self expectationWithDescription:@"Bank account creation"];
+    XCTestExpectation *expectation = [self expectationWithDescription:@"Apple pay token creation"];
     [client createTokenWithPayment:payment
                         completion:^(STPToken *token, NSError *error) {
                             [expectation fulfill];
diff --git a/Tests/Tests/STPBankAccountFunctionalTest.m b/Tests/Tests/STPBankAccountFunctionalTest.m
@@ -24,7 +24,7 @@ - (void)testCreateAndRetreiveBankAccountToken {
     bankAccount.routingNumber = @"110000000";
     bankAccount.country = @"US";
 
-    STPAPIClient *client = [[STPAPIClient alloc] initWithPublishableKey:@"pk_test_5fhKkYDKKNr4Fp6q7Mq9CwJd"];
+    STPAPIClient *client = [[STPAPIClient alloc] initWithPublishableKey:@"pk_test_vOo1umqsYxSrP5UXfOeL3ecm"];
 
     XCTestExpectation *expectation = [self expectationWithDescription:@"Bank account creation"];
     [client createTokenWithBankAccount:bankAccount
diff --git a/Tests/Tests/STPBankAccountTest.m b/Tests/Tests/STPBankAccountTest.m
diff --git a/Tests/Tests/STPCardFunctionalTest.m b/Tests/Tests/STPCardFunctionalTest.m
diff --git a/Tests/Tests/STPCardTest.m b/Tests/Tests/STPCardTest.m
diff --git a/Tests/Tests/STPFormEncoderTest.m b/Tests/Tests/STPFormEncoderTest.m
diff --git a/Tests/Tests/STPTokenTest.m b/Tests/Tests/STPTokenTest.m

Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,7 @@ @interface STPBankAccount ()`
`16`	`16`	`@property (nonatomic, readwrite) NSString *bankName;`
`17`	`17`	`@property (nonatomic, readwrite) NSString *fingerprint;`
`18`	`18`	`@property (nonatomic) STPBankAccountStatus status;`
	`19`	`+@property (nonatomic, readwrite, nonnull, copy) NSDictionary *allResponseFields;`
`19`	`20`
`20`	`21`	`@end`
`21`	`22`
`@@ -90,6 +91,8 @@ + (instancetype)decodedObjectFromAPIResponse:(NSDictionary *)response {`
`90`	`91`	`} else if ([status isEqual: @"errored"]) {`
`91`	`92`	`bankAccount.status = STPBankAccountStatusErrored;`
`92`	`93`	`}`
	`94`	`+`
	`95`	`+ bankAccount.allResponseFields = dict;`
`93`	`96`	`return bankAccount;`
`94`	`97`	`}`
`95`	`98`
Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,7 @@ @interface STPToken()`
`17`	`17`	`@property (nonatomic, nullable) STPCard *card;`
`18`	`18`	`@property (nonatomic, nullable) STPBankAccount *bankAccount;`
`19`	`19`	`@property (nonatomic, nullable) NSDate *created;`
	`20`	`+@property (nonatomic, readwrite, nonnull, copy) NSDictionary *allResponseFields;`
`20`	`21`	`@end`
`21`	`22`
`22`	`23`	`@implementation STPToken`
`@@ -86,6 +87,8 @@ + (instancetype)decodedObjectFromAPIResponse:(NSDictionary *)response {`
`86`	`87`	`if (bankAccountDictionary) {`
`87`	`88`	`token.bankAccount = [STPBankAccount decodedObjectFromAPIResponse:bankAccountDictionary];`
`88`	`89`	`}`
	`90`	`+`
	`91`	`+ token.allResponseFields = dict;`
`89`	`92`	`return token;`
`90`	`93`	`}`
`91`	`94`