chore(docs): add jsdoc to all functions

Author: stfsy

lib/index.js

@@ -97,7 +97,27 @@ class Subscriptions {
     /**
      * Adds a placeholder for a subscription so that webhooks only need to append to existing subscription
      * 
-     * @param {Array<String>} ids 
+     * The `ids` parameter must point to an existing document in a collection or subcollection. The number
+     * of necessary elements in the `ids` array corresponds to the number of resources/collections that were
+     * passed to the constructor
+     * 
+     * @example <caption>Subscriptions stored in a collection called api_clients</caption>
+     * const { Subscriptions } = require('@discue/paddle-firebase-integration')
+     * const subscriptions = new Subscriptions('api_clients')
+     * // assuming api_client with id 4815162342 exists we can simple play an array with one element
+     * const { passthrough } = await subscriptions.addSubscriptionPlaceholder(['4815162342'])
+
+    * @example <caption>Subscriptions stored in a subcollection called external</caption>
+     * const { Subscriptions } = require('@discue/paddle-firebase-integration')
+     * 
+     * const subscriptions = new Subscriptions('api_clients/external')
+     * // as subscriptions are stored in a sub collection we need to pass the id of the parent and the child document
+     * // 4815162342: api_client id
+     * // 123: external client id
+     * const { passthrough } = await subscriptions.addSubscriptionPlaceholder(['4815162342', '123'])
+     * 
+     * @param {Array<String>} ids ids to the target document
+     * @returns {object} an object containing the `passthrough` parameter required to correlate webhooks with this subscription
      */
     async addSubscriptionPlaceholder(ids) {
         const statusModel = {
@@ -123,6 +143,9 @@ class Subscriptions {
     }
 
     /**
+     * Add an subscription created event. Uses the `passthrough` parameter to identify the target subscription.
+     * 
+     * You can directly pass the payload of the respective `subscription_created` webhook.
      * 
      * @param {SubscriptionCreatedPayload} subscription 
      */
@@ -160,6 +183,9 @@ class Subscriptions {
     }
 
     /**
+     * Add an subscription updated event. Uses the `passthrough` parameter to identify the target subscription.
+     * 
+     * You can directly pass the payload of the respective `subscription_updated` webhook.
      * 
      * @param {SubscriptionUpdatedPayload} subscription 
      */
@@ -196,6 +222,9 @@ class Subscriptions {
     }
 
     /**
+     * Add an subscription cancelled event. Uses the `passthrough` parameter to identify the target subscription.
+     * 
+     * You can directly pass the payload of the respective `subscription_cancelled` webhook.
      * 
      * @param {SubscriptionCancelledPayload} subscription 
      */
@@ -226,23 +255,14 @@ class Subscriptions {
         await this._storage.update(ids, flatModel)
     }
 
-    /**
-     * 
-     * @param {Object} subscription 
-     * @param {Date} [atDate=new Date()] date for the calculation  
-     * @returns {boolean} true subscription is active
-     */
-    async isSubscriptionActive(subscription, atDate = new Date()) {
-        return this._isOneOfSubscriptionsActive(subscription, atDate)
-    }
-
     /**
      * @typedef {Object} StartAndEndDate
      * @property {String} start - subscription start date as ISO formatted string
      * @property {String} start - subscription end date as ISO formatted string
      */
 
     /**
+     * Returns start and end dates for all subscription plans found in the document.
      * 
      * @param {Object} subscription 
      * @returns {StartAndEndDate} containing the start and end date
@@ -255,9 +275,11 @@ class Subscriptions {
             return context
         }, {})
     }
-  
+
     /**
+     * Returns start and end dates for the given list of status objects. 
      * 
+     * @private
      * @param {Object} subscription 
      * @returns {StartAndEndDate} containing the start and end date
      */
@@ -283,6 +305,7 @@ class Subscriptions {
     }
 
     /**
+     * Returns a list of payments for all subscription plans found in the document.
      * 
      * @param {Object} subscription 
      * @returns {Object}
@@ -297,7 +320,9 @@ class Subscriptions {
     }
 
     /**
+     * Returns a list of payments sorted by event_time descending.
      * 
+     * @private
      * @param {Object} subscription 
      * @returns {Array<Object>} containing the start and end date
      */
@@ -369,6 +394,7 @@ class Subscriptions {
     }
 
     /**
+     * Returns a list of update and changes events for all subscription plans found in the document.
      * 
      * @param {Object} subscription 
      * @returns {Object}
@@ -383,6 +409,7 @@ class Subscriptions {
     }
 
     /**
+     * Returns a list of update events sorted by event_time descending.
      * 
      * @param {Array<Object>} status
      * @returns {Array<Object>} containing the start and end date
@@ -400,10 +427,17 @@ class Subscriptions {
     }
 
     /**
+     * Returns the status of each subscription found in the document. 
+     * 
+     * For each found subscription the method will add a boolean value
+     * indicating the subscription plan is active (true) or not active (false).
+     * 
+     * Unless the second parameter is passed, the status will always be calculated
+     * using the current time
      * 
      * @param {Object} subscription
      * @param {Date} [atDate=new Date()] date for the calculation  
-     * @returns {boolean} true if an active subscription was given
+     * @returns {Object} true if an active subscription was given
      */
     async getAllSubscriptionsStatus(subscriptions, atDate = new Date()) {
         const result = {}
@@ -422,6 +456,7 @@ class Subscriptions {
 
     /**
      * 
+     * @private
      * @param {Array<Object>} statusOrPayments 
      * @param {Number} validUntilMillis 
      * @returns 
@@ -440,18 +475,24 @@ class Subscriptions {
     }
 
     /**
-    * 
     * Returns true if the given status has a description that we recognize as active
-    * 
-    * <strong>Status must be decrypted</strong>
-    * 
+    *  
+    * @private
     * @param {Object} activeStatus 
     * @returns {Boolean} true or false
     */
     _isSubscriptionStatusCurrentlyActive(status) {
         return SUBSCRIPTION_ACTIVE_STATUS.includes(status.description)
     }
 
+    /**
+     * Add a payment event. Uses the `passthrough` parameter to identify the target subscription.
+     * 
+     * You can directly pass the payload of the respective `subscription_payment_succeeded` webhook.
+     * 
+     * @param {Object} payment 
+     * @returns 
+     */
     async addSuccessfulPayment(payment) {
         if (!payment) {
             return Promise.reject(new Error(this.ERROR_INVALID_ARGUMENTS))
@@ -470,6 +511,14 @@ class Subscriptions {
         await this._storage.update(ids, flatModel)
     }
 
+    /**
+     * Add a payment event. Uses the `passthrough` parameter to identify the target subscription.
+     * 
+     * You can directly pass the payload of the respective `subscription_payment_failed` webhook.
+     * 
+     * @param {Object} payment 
+     * @returns 
+     */
     async addFailedPayment(payment) {
         if (!payment) {
             return Promise.reject(new Error(this.ERROR_INVALID_ARGUMENTS))
@@ -488,6 +537,14 @@ class Subscriptions {
         await this._storage.update(ids, flatModel)
     }
 
+    /**
+     * Add a payment event. Uses the `passthrough` parameter to identify the target subscription.
+     * 
+     * You can directly pass the payload of the respective `subscription_payment_refunded` webhook.
+     * 
+     * @param {Object} payment 
+     * @returns 
+     */
     async addRefundedPayment(payment) {
         if (!payment) {
             return Promise.reject(new Error(this.ERROR_INVALID_ARGUMENTS))