Merge pull request #813 from stripe/bg-public-customercontext-methods

add detachSourceFromCustomer and updateCustomer to BackendAPIAdapter

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 * Restores `[STPCard brandFromString:]` method which was marked as deprecated in a recent version [#801](https://github.com/stripe/stripe-ios/pull/801)
 * Adds `[STPBankAccount metadata]` and `[STPCard metadata]` read-only accessors and improves annotation for `[STPSource metadata]` [#808](https://github.com/stripe/stripe-ios/pull/808)
+* Un-deprecates `STPBackendAPIAdapter` and all associated methods.
 
 ## 11.3.0 2017-09-13
 * Adds support for creating `STPSourceParams` for P24 source [#779](https://github.com/stripe/stripe-ios/pull/779)

Stripe.xcodeproj/project.pbxproj

@@ -443,8 +443,6 @@
 		C15993471D8829C00047950D /* [email protected] in Resources */ = {isa = PBXBuildFile; fileRef = C15993221D8807930047950D /* [email protected] */; };
 		C15B02731EA176090026E606 /* StripeErrorTest.m in Sources */ = {isa = PBXBuildFile; fileRef = C15B02721EA176090026E606 /* StripeErrorTest.m */; };
 		C16F66AB1CA21BAC006A21B5 /* STPFormTextFieldTest.m in Sources */ = {isa = PBXBuildFile; fileRef = C16F66AA1CA21BAC006A21B5 /* STPFormTextFieldTest.m */; };
-		C16FC79D1EEB39C3001CBD3A /* STPCustomerContext+Private.h in Headers */ = {isa = PBXBuildFile; fileRef = C16FC79C1EEB39C3001CBD3A /* STPCustomerContext+Private.h */; };
-		C16FC79E1EEB39C3001CBD3A /* STPCustomerContext+Private.h in Headers */ = {isa = PBXBuildFile; fileRef = C16FC79C1EEB39C3001CBD3A /* STPCustomerContext+Private.h */; };
 		C1717DB11CC00ED60009CF4A /* STPAddress.h in Headers */ = {isa = PBXBuildFile; fileRef = C1080F471CBECF7B007B2D89 /* STPAddress.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		C1785F5C1EC60B5E00E9CFAC /* STPCardIOProxy.h in Headers */ = {isa = PBXBuildFile; fileRef = C1785F5A1EC60B5E00E9CFAC /* STPCardIOProxy.h */; };
 		C1785F5D1EC60B5E00E9CFAC /* STPCardIOProxy.h in Headers */ = {isa = PBXBuildFile; fileRef = C1785F5A1EC60B5E00E9CFAC /* STPCardIOProxy.h */; };
@@ -1043,7 +1041,6 @@
 		C15993321D8808680047950D /* STPShippingMethodTableViewCell.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = STPShippingMethodTableViewCell.m; sourceTree = "<group>"; };
 		C15B02721EA176090026E606 /* StripeErrorTest.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = StripeErrorTest.m; sourceTree = "<group>"; };
 		C16F66AA1CA21BAC006A21B5 /* STPFormTextFieldTest.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = STPFormTextFieldTest.m; sourceTree = "<group>"; };
-		C16FC79C1EEB39C3001CBD3A /* STPCustomerContext+Private.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = "STPCustomerContext+Private.h"; sourceTree = "<group>"; };
 		C1785F5A1EC60B5E00E9CFAC /* STPCardIOProxy.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = STPCardIOProxy.h; sourceTree = "<group>"; };
 		C1785F5B1EC60B5E00E9CFAC /* STPCardIOProxy.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = STPCardIOProxy.m; sourceTree = "<group>"; };
 		C17A030B1CBEE7A2006C819F /* STPAddressFieldTableViewCell.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = STPAddressFieldTableViewCell.h; sourceTree = "<group>"; };
@@ -1831,7 +1828,6 @@
 			isa = PBXGroup;
 			children = (
 				04E39F5A1CECFAFD00AF3B96 /* STPPaymentContext+Private.h */,
-				C16FC79C1EEB39C3001CBD3A /* STPCustomerContext+Private.h */,
 			);
 			name = PaymentContext;
 			sourceTree = "<group>";
@@ -2067,7 +2063,6 @@
 				04F94DA51D229F21004FC826 /* STPPaymentContext+Private.h in Headers */,
 				F12829DB1D7747E4008B10D6 /* STPBundleLocator.h in Headers */,
 				8BD87B891EFB131800269C2B /* STPSourceCardDetails+Private.h in Headers */,
-				C16FC79E1EEB39C3001CBD3A /* STPCustomerContext+Private.h in Headers */,
 				04827D161D257764002DB3E8 /* STPImageLibrary+Private.h in Headers */,
 				049E84EC1A605EF0000B66CD /* StripeError.h in Headers */,
 				046FE9A31CE5608000DA6A7B /* STPPaymentActivityIndicatorView.h in Headers */,
@@ -2240,7 +2235,6 @@
 				04B31DE61D09D25F00EF1631 /* STPPaymentMethodsInternalViewController.h in Headers */,
 				04CDB4FE1A5F30A700B854EE /* STPAPIClient.h in Headers */,
 				045D712C1CF4ED7600F6CD65 /* STPBINRange.h in Headers */,
-				C16FC79D1EEB39C3001CBD3A /* STPCustomerContext+Private.h in Headers */,
 				C1D7B51A1E36B8B9002181F5 /* STPSourceParams.h in Headers */,
 				04827D101D2575C6002DB3E8 /* STPImageLibrary.h in Headers */,
 				F152322A1EA9306100D65C67 /* NSURLComponents+Stripe.h in Headers */,

Stripe/PublicHeaders/STPBackendAPIAdapter.h

@@ -19,40 +19,105 @@ NS_ASSUME_NONNULL_BEGIN
 @class STPCard, STPToken;
 
 /**
- You should make your application's API client conform to this interface in order to use it with an `STPPaymentContext`. It provides a "bridge" from the prebuilt UI we expose (such as `STPPaymentMethodsViewController`) to your backend to fetch the information it needs to power those views. To read about how to implement this protocol, see https://stripe.com/docs/mobile/ios/standard#prepare-your-api . To see examples of implementing these APIs, see MyAPIClient.swift in our example project and https://github.com/stripe/example-ios-backend .
+ Typically, you will not need to implement this protocol yourself. You
+ should instead use `STPCustomerContext`, which implements <STPBackendAPIAdapter>
+ and manages retrieving and updating a Stripe customer for you.
+ @see STPCustomerContext.h
 
- @deprecated Use `STPCustomerContext`.
- Instead of providing your own backend API adapter, you can now create an
- `STPCustomerContext`, which will manage retrieving and updating a
- Stripe customer for you. @see STPCustomerContext.h
+ If you would prefer retrieving and updating your Stripe customer object via
+ your own backend instead of using `STPCustomerContext`, you should make your 
+ application's API client conform to this interface. It provides a "bridge" from 
+ the prebuilt UI we expose (such as `STPPaymentMethodsViewController`) to your
+ backend to fetch the information it needs to power those views.
  */
-__attribute__((deprecated))
 @protocol STPBackendAPIAdapter<NSObject>
 
 /**
- Retrieve the cards to be displayed inside a payment context. On your backend, retrieve the Stripe customer associated with your currently logged-in user (see https://stripe.com/docs/api#retrieve_customer ), and return the raw JSON response from the Stripe API. (For an example Ruby implementation of this API, see https://github.com/stripe/example-ios-backend/blob/master/web.rb#L40 ). Back in your iOS app, after you've called this API, deserialize your API response into an `STPCustomer` object (you can use the `STPCustomerDeserializer` class to do this). See MyAPIClient.swift in our example project to see this in action.
+ Retrieve the cards to be displayed inside a payment context. 
+ 
+ If you are not using STPCustomerContext:
+ On your backend, retrieve the Stripe customer associated with your currently 
+ logged-in user ( https://stripe.com/docs/api#retrieve_customer ), and return
+ the raw JSON response from the Stripe API. Back in your iOS app, after you've 
+ called this API, deserialize your API response into an `STPCustomer` object
+ (you can use the `STPCustomerDeserializer` class to do this).
 
  @see STPCard
  @param completion call this callback when you're done fetching and parsing the above information from your backend. For example, `completion(customer, nil)` (if your call succeeds) or `completion(nil, error)` if an error is returned.
  */
 - (void)retrieveCustomer:(nullable STPCustomerCompletionBlock)completion;
 
 /**
- Adds a payment source to a customer. On your backend, retrieve the Stripe customer associated with your logged-in user. Then, call the Update Customer method on that customer as described at https://stripe.com/docs/api#update_customer (for an example Ruby implementation of this API, see https://github.com/stripe/example-ios-backend/blob/master/web.rb#L60 ). If this API call succeeds, call `completion(nil)`. Otherwise, call `completion(error)` with the error that occurred.
+ Adds a payment source to a customer. 
+
+ If you are implementing your own <STPBackendAPIAdapter>:
+ On your backend, retrieve the Stripe customer associated with your logged-in user. 
+ Then, call the Update Customer method on that customer
+ ( https://stripe.com/docs/api#update_customer ). If this API call succeeds,
+ call `completion(nil)`. Otherwise, call `completion(error)` with the error that
+ occurred.
 
  @param source     a valid payment source, such as a card token.
- @param completion call this callback when you're done adding the token to the customer on your backend. For example, `completion(nil)` (if your call succeeds) or `completion(error)` if an error is returned.
+ @param completion call this callback when you're done adding the token to the 
+ customer on your backend. For example, `completion(nil)` (if your call succeeds) 
+ or `completion(error)` if an error is returned.
  */
 - (void)attachSourceToCustomer:(id<STPSourceProtocol>)source completion:(STPErrorBlock)completion;
 
 /**
- Change a customer's `default_source` to be the provided card. On your backend, retrieve the Stripe customer associated with your logged-in user. Then, call the Customer Update method as described at https://stripe.com/docs/api#update_customer , specifying default_source to be the value of source.stripeID (for an example Ruby implementation of this API, see https://github.com/stripe/example-ios-backend/blob/master/web.rb#L82 ). If this API call succeeds, call `completion(nil)`. Otherwise, call `completion(error)` with the error that occurred.
+ Change a customer's `default_source` to be the provided card. 
+
+ If you are implementing your own <STPBackendAPIAdapter>:
+ On your backend, retrieve the Stripe customer associated with your logged-in user.
+ Then, call the Customer Update method ( https://stripe.com/docs/api#update_customer )
+ specifying default_source to be the value of source.stripeID. If this API call 
+ succeeds, call `completion(nil)`. Otherwise, call `completion(error)` with the 
+ error that occurred.
 
  @param source     The newly-selected default source for the user.
- @param completion call this callback when you're done selecting the new default source for the customer on your backend. For example, `completion(nil)` (if your call succeeds) or `completion(error)` if an error is returned.
+ @param completion call this callback when you're done selecting the new default 
+ source for the customer on your backend. For example, `completion(nil)` (if 
+ your call succeeds) or `completion(error)` if an error is returned.
  */
 - (void)selectDefaultCustomerSource:(id<STPSourceProtocol>)source completion:(STPErrorBlock)completion;
 
+@optional
+
+/**
+ Deletes the given source from the customer.
+ 
+ If you are implementing your own <STPBackendAPIAdapter>:
+ On your backend, retrieve the Stripe customer associated with your logged-in user.
+ Then, call the Delete Card method ( https://stripe.com/docs/api#delete_card )
+ specifying id to be the value of source.stripeID. If this API call
+ succeeds, call `completion(nil)`. Otherwise, call `completion(error)` with the
+ error that occurred.
+
+ @param source    The source to delete from the customer
+ @param completion call this callback when you're done deleting the source from
+ the customer on your backend. For example, `completion(nil)` (if your call
+ succeeds) or `completion(error)` if an error is returned.
+ */
+- (void)detachSourceFromCustomer:(id<STPSourceProtocol>)source completion:(nullable STPErrorBlock)completion;
+
+/**
+ Sets the given shipping address on the customer.
+ 
+ If you are implementing your own <STPBackendAPIAdapter>:
+ On your backend, retrieve the Stripe customer associated with your logged-in user.
+ Then, call the Customer Update method ( https://stripe.com/docs/api#update_customer )
+ specifying shipping to be the given shipping address. If this API call succeeds, 
+ call `completion(nil)`. Otherwise, call `completion(error)` with the error that occurred.
+
+ @param shipping   The shipping address to set on the customer
+ @param completion call this callback when you're done updating the customer on
+ your backend. For example, `completion(nil)` (if your call succeeds) or
+ `completion(error)` if an error is returned.
+
+ @see https://stripe.com/docs/api#update_customer
+ */
+- (void)updateCustomerWithShippingAddress:(STPAddress *)shipping completion:(nullable STPErrorBlock)completion;
+
 @end
 
 NS_ASSUME_NONNULL_END

Stripe/PublicHeaders/STPCustomer.h

@@ -29,13 +29,10 @@ NS_ASSUME_NONNULL_BEGIN
  @param sources       All of the customer's payment sources. This might be an empty array.
 
  @return an instance of STPCustomer
-
- @deprecated Use `STPCustomerContext` to manage retrieving and updating a 
- Customer. You will no longer need to initialize an `STPCustomer`.
  */
 + (instancetype)customerWithStripeID:(NSString *)stripeID
                        defaultSource:(nullable id<STPSourceProtocol>)defaultSource
-                             sources:(NSArray<id<STPSourceProtocol>> *)sources __attribute__((deprecated));
+                             sources:(NSArray<id<STPSourceProtocol>> *)sources;
 
 /**
  The Stripe ID of the customer, e.g. `cus_1234`
@@ -65,28 +62,30 @@ NS_ASSUME_NONNULL_BEGIN
 @interface STPCustomerDeserializer : NSObject
 
 /**
- Initialize a customer deserializer. The `data`, `urlResponse`, and `error` parameters are intended to be passed from an `NSURLSessionDataTask` callback. After it has been initialized, you can inspect the `error` and `customer` properties to see if the deserialization was successful. If `error` is nil, `customer` will be non-nil (and vice versa).
+ Initialize a customer deserializer. The `data`, `urlResponse`, and `error` 
+ parameters are intended to be passed from an `NSURLSessionDataTask` callback. 
+ After it has been initialized, you can inspect the `error` and `customer` 
+ properties to see if the deserialization was successful. If `error` is nil, 
+ `customer` will be non-nil (and vice versa).
 
  @param data        An `NSData` object representing encoded JSON for a Customer object
  @param urlResponse The URL response obtained from the `NSURLSessionTask`
- @param error       Any error that occurred from the URL session task (if this is non-nil, the `error` property will be set to this value after initialization).
-
- @deprecated Use `STPCustomerContext` to manage retrieving and updating a
- Customer. You will no longer need to deserialize an `STPCustomer`.
+ @param error       Any error that occurred from the URL session task (if this 
+ is non-nil, the `error` property will be set to this value after initialization).
  */
 - (instancetype)initWithData:(nullable NSData *)data
                  urlResponse:(nullable NSURLResponse *)urlResponse
-                       error:(nullable NSError *)error __attribute__((deprecated));
+                       error:(nullable NSError *)error;
 
 /**
- Initializes a customer deserializer with a JSON dictionary. This JSON should be in the exact same format as what the Stripe API returns. If it's successfully parsed, the `customer` parameter will be present after initialization; otherwise `error` will be present.
+ Initializes a customer deserializer with a JSON dictionary. This JSON should be 
+ in the exact same format as what the Stripe API returns. If it's successfully 
+ parsed, the `customer` parameter will be present after initialization; 
+ otherwise `error` will be present.
 
  @param json a JSON dictionary.
-
- @deprecated Use `STPCustomerContext` to manage retrieving and updating a
- Customer. You will no longer need to deserialize an `STPCustomer`.
  */
-- (instancetype)initWithJSONResponse:(id)json __attribute__((deprecated));
+- (instancetype)initWithJSONResponse:(id)json;
 
 /**
  If a customer was successfully parsed from the response, it will be set here. Otherwise, this value wil be nil (and the `error` property will explain what went wrong).

Stripe/PublicHeaders/STPCustomerContext.h

@@ -15,8 +15,6 @@ NS_ASSUME_NONNULL_BEGIN
 @protocol STPEphemeralKeyProvider;
 @class STPEphemeralKey, STPEphemeralKeyManager;
 
-#pragma clang diagnostic push
-#pragma clang diagnostic ignored "-Wdeprecated"
 /**
  An `STPCustomerContext` retrieves and updates a Stripe customer using
  an ephemeral key, a short-lived API key scoped to a specific customer object.
@@ -26,7 +24,6 @@ NS_ASSUME_NONNULL_BEGIN
  new ephemeral key for the Customer object associated with the new user.
  */
 @interface STPCustomerContext : NSObject <STPBackendAPIAdapter>
-#pragma clang diagnostic pop
 
 /**
  Initializes a new `STPCustomerContext` with the specified key provider.