Updated method signatures and added JSDocs

refs https://github.com/TryGhost/Team/issues/1674

- While preparing the changes had a look around and made small refactors to understand the codebase a little better. In general it's best to keep the method parameters as small and precise as possible instead of passing around a "bag-of-all-the-things" like "data" around

ghost/members-api/lib/repositories/member.js

@@ -1335,8 +1335,10 @@ module.exports = class MemberRepository {
      *
      * @param {Object} data
      * @param {String} data.id - member ID
+     * @param {Object} options
+     * @param {Object} [options.transacting]
      */
-    async cancelComplimentarySubscription({id}) {
+    async cancelComplimentarySubscription({id}, options) {
         if (!this._stripeAPIService.configured) {
             throw new errors.BadRequestError({message: tpl(messages.noStripeConnection, {action: 'cancel Complimentary Subscription'})});
         }
@@ -1357,7 +1359,7 @@ module.exports = class MemberRepository {
                     await this.linkSubscription({
                         id: id,
                         subscription: updatedSubscription
-                    });
+                    }, options);
                 } catch (err) {
                     logging.error(`There was an error cancelling subscription ${subscription.get('subscription_id')}`);
                     logging.error(err);

ghost/members-api/lib/services/member-bread.js

@@ -126,24 +126,24 @@ module.exports = class MemberBREADService {
         try {
             for (const subscriptionModel of subscriptions) {
                 const offerId = subscriptionModel.get('offer_id');
-    
+
                 if (!offerId) {
                     continue;
                 }
-                
+
                 let offer = fetchedOffers.get(offerId);
                 if (!offer) {
                     offer = await this.offersAPI.getOffer({id: offerId});
                     fetchedOffers.set(offerId, offer);
                 }
-    
+
                 subscriptionOffers.set(subscriptionModel.get('subscription_id'), offer);
             }
         } catch (e) {
             logging.error(`Failed to load offers for subscriptions - ${subscriptions.map(s => s.id).join(', ')}.`);
             logging.error(e);
         }
-        
+
         return subscriptionOffers;
     }
 
@@ -262,6 +262,10 @@ module.exports = class MemberBREADService {
             });
         }
 
+        if (data.comped) {
+            await this.memberRepository.setComplimentarySubscription(model, options);
+        }
+
         return this.read({id: model.id}, options);
     }
 
@@ -283,6 +287,24 @@ module.exports = class MemberBREADService {
             throw error;
         }
 
+        if (this.stripeService.configured) {
+            const hasCompedSubscription = !!model.related('stripeSubscriptions').find(sub => sub.get('plan_nickname') === 'Complimentary' && sub.get('status') === 'active');
+
+            if (typeof data.comped === 'boolean') {
+                if (data.comped && !hasCompedSubscription) {
+                    await this.memberRepository.setComplimentarySubscription(model, {
+                        context: options.context,
+                        transacting: options.transacting
+                    });
+                } else if (!(data.comped) && hasCompedSubscription) {
+                    await this.memberRepository.cancelComplimentarySubscription(model, {
+                        context: options.context,
+                        transacting: options.transacting
+                    });
+                }
+            }
+        }
+
         return this.read({id: model.id}, options);
     }