Merge pull request #282 from recurly/v3-v2021-02-25-1667937927

Generated Latest Changes for v2021-02-25 (External Subscriptions feature)

lib/recurly/Client.js

@@ -683,7 +683,7 @@ class Client extends BaseClient {
   }
 
   /**
-   * Show the coupon redemptions for an account
+   * List the coupon redemptions for an account
    *
    * API docs: {@link https://developers.recurly.com/api/v2021-02-25#operation/list_account_coupon_redemptions}
    *
@@ -729,7 +729,7 @@ class Client extends BaseClient {
   }
 
   /**
-   * Show the coupon redemptions that are active on an account
+   * List the coupon redemptions that are active on an account
    *
    * API docs: {@link https://developers.recurly.com/api/v2021-02-25#operation/list_active_coupon_redemptions}
    *
@@ -1044,7 +1044,7 @@ class Client extends BaseClient {
   }
 
   /**
-   * Fetch a list of an account's notes
+   * List an account's notes
    *
    * API docs: {@link https://developers.recurly.com/api/v2021-02-25#operation/list_account_notes}
    *
@@ -2226,6 +2226,76 @@ endpoint to obtain only the newly generated `UniqueCouponCodes`.
     return this._makeRequest('DELETE', path, null, options)
   }
 
+  /**
+   * List a site's external products
+   *
+   * API docs: {@link https://developers.recurly.com/api/v2021-02-25#operation/list_external_products}
+   *
+   *
+   * @param {Object} options - Optional configurations for the request
+   * @param {Object} options.params - The optional url parameters for this request.
+   * @param {string} options.params.sort - Sort field. You *really* only want to sort by `updated_at` in ascending
+   *   order. In descending order updated records will move behind the cursor and could
+   *   prevent some records from being returned.
+   *
+   * @return {Pager<ExternalProduct>} A list of the the external_products on a site.
+   */
+  listExternalProducts (options = {}) {
+    let path = '/external_products'
+    path = this._interpolatePath(path)
+    return new Pager(this, path, options)
+  }
+
+  /**
+   * Fetch an external product
+   *
+   * API docs: {@link https://developers.recurly.com/api/v2021-02-25#operation/get_external_product}
+   *
+   *
+   * @param {string} externalProductId - External product id
+   * @return {Promise<ExternalProduct>} Settings for an external product.
+   */
+  async getExternalProduct (externalProductId, options = {}) {
+    let path = '/external_products/{external_product_id}'
+    path = this._interpolatePath(path, { 'external_product_id': externalProductId })
+    return this._makeRequest('GET', path, null, options)
+  }
+
+  /**
+   * List a site's external subscriptions
+   *
+   * API docs: {@link https://developers.recurly.com/api/v2021-02-25#operation/list_external_subscriptions}
+   *
+   *
+   * @param {Object} options - Optional configurations for the request
+   * @param {Object} options.params - The optional url parameters for this request.
+   * @param {string} options.params.sort - Sort field. You *really* only want to sort by `updated_at` in ascending
+   *   order. In descending order updated records will move behind the cursor and could
+   *   prevent some records from being returned.
+   *
+   * @return {Pager<ExternalSubscription>} A list of the the external_subscriptions on a site.
+   */
+  listExternalSubscriptions (options = {}) {
+    let path = '/external_subscriptions'
+    path = this._interpolatePath(path)
+    return new Pager(this, path, options)
+  }
+
+  /**
+   * Fetch an external subscription
+   *
+   * API docs: {@link https://developers.recurly.com/api/v2021-02-25#operation/get_external_subscription}
+   *
+   *
+   * @param {string} externalSubscriptionId - External subscription id
+   * @return {Promise<ExternalSubscription>} Settings for an external subscription.
+   */
+  async getExternalSubscription (externalSubscriptionId, options = {}) {
+    let path = '/external_subscriptions/{external_subscription_id}'
+    path = this._interpolatePath(path, { 'external_subscription_id': externalSubscriptionId })
+    return this._makeRequest('GET', path, null, options)
+  }
+
   /**
    * List a site's invoices
    *
@@ -2625,7 +2695,7 @@ endpoint to obtain only the newly generated `UniqueCouponCodes`.
   }
 
   /**
-   * Show the coupon redemptions applied to an invoice
+   * List the coupon redemptions applied to an invoice
    *
    * API docs: {@link https://developers.recurly.com/api/v2021-02-25#operation/list_invoice_coupon_redemptions}
    *
@@ -3978,7 +4048,7 @@ endpoint to obtain only the newly generated `UniqueCouponCodes`.
   }
 
   /**
-   * Show the coupon redemptions for a subscription
+   * List the coupon redemptions for a subscription
    *
    * API docs: {@link https://developers.recurly.com/api/v2021-02-25#operation/list_subscription_coupon_redemptions}
    *
@@ -4442,7 +4512,7 @@ endpoint to obtain only the newly generated `UniqueCouponCodes`.
   }
 
   /**
-   * Show the dunning campaigns for a site
+   * List the dunning campaigns for a site
    *
    * API docs: {@link https://developers.recurly.com/api/v2021-02-25#operation/list_dunning_campaigns}
    *
@@ -4462,7 +4532,7 @@ endpoint to obtain only the newly generated `UniqueCouponCodes`.
   }
 
   /**
-   * Show the settings for a dunning campaign
+   * Fetch a dunning campaign
    *
    * API docs: {@link https://developers.recurly.com/api/v2021-02-25#operation/get_dunning_campaign}
    *
@@ -4513,7 +4583,7 @@ endpoint to obtain only the newly generated `UniqueCouponCodes`.
   }
 
   /**
-   * Show the settings for an invoice template
+   * Fetch an invoice template
    *
    * API docs: {@link https://developers.recurly.com/api/v2021-02-25#operation/get_invoice_template}
    *
@@ -4528,7 +4598,7 @@ endpoint to obtain only the newly generated `UniqueCouponCodes`.
   }
 
   /**
-   * Show all entitlements granted to an account
+   * List entitlements granted to an account
    *
    * API docs: {@link https://developers.recurly.com/api/v2021-02-25#operation/list_entitlements}
    *
@@ -4548,6 +4618,27 @@ endpoint to obtain only the newly generated `UniqueCouponCodes`.
     path = this._interpolatePath(path, { 'account_id': accountId })
     return new Pager(this, path, options)
   }
+
+  /**
+   * List an account's external subscriptions
+   *
+   * API docs: {@link https://developers.recurly.com/api/v2021-02-25#operation/list_account_external_subscriptions}
+   *
+   *
+   * @param {string} accountId - Account ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`. For code use prefix `code-`, e.g. `code-bob`.
+   * @param {Object} options - Optional configurations for the request
+   * @param {Object} options.params - The optional url parameters for this request.
+   * @param {string} options.params.sort - Sort field. You *really* only want to sort by `updated_at` in ascending
+   *   order. In descending order updated records will move behind the cursor and could
+   *   prevent some records from being returned.
+   *
+   * @return {Pager<ExternalSubscription>} A list of the the external_subscriptions on an account.
+   */
+  listAccountExternalSubscriptions (accountId, options = {}) {
+    let path = '/accounts/{account_id}/external_subscriptions'
+    path = this._interpolatePath(path, { 'account_id': accountId })
+    return new Pager(this, path, options)
+  }
 }
 
 module.exports = Client

lib/recurly/resources/AddOn.js

@@ -34,9 +34,10 @@ const Resource = require('../Resource')
  * @prop {string} revenueScheduleType - When this add-on is invoiced, the line item will use this revenue schedule. If `item_code`/`item_id` is part of the request then `revenue_schedule_type` must be absent in the request as the value will be set from the item.
  * @prop {string} state - Add-ons can be either active or inactive.
  * @prop {string} taxCode - Used by Avalara, Vertex, and Recurly’s EU VAT tax feature. The tax code values are specific to each tax system. If you are using Recurly’s EU VAT feature you can use `unknown`, `physical`, or `digital`.
- * @prop {string} tierType - The pricing model for the add-on.  For more information, [click here](https://docs.recurly.com/docs/billing-models#section-quantity-based). See our [Guide](https://developers.recurly.com/guides/item-addon-guide.html) for an overview of how to configure quantity-based pricing models.
+ * @prop {string} tierType - The pricing model for the add-on.  For more information, [click here](https://docs.recurly.com/docs/billing-models#section-quantity-based). See our [Guide](https://recurly.com/developers/guides/item-addon-guide.html) for an overview of how to configure quantity-based pricing models.
  * @prop {Array.<Tier>} tiers - Tiers
  * @prop {Date} updatedAt - Last updated at
+ * @prop {string} usageCalculationType - The type of calculation to be employed for an add-on.  Cumulative billing will sum all usage records created in the current billing cycle.  Last-in-period billing will apply only the most recent usage record in the billing period.  If no value is specified, cumulative billing will be used.
  * @prop {number} usagePercentage - The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0.
  * @prop {string} usageTimeframe - The time at which usage totals are reset for billing purposes.
  * @prop {string} usageType - Type of usage, returns usage type if `add_on_type` is `usage`.
@@ -69,6 +70,7 @@ class AddOn extends Resource {
       tierType: String,
       tiers: ['Tier'],
       updatedAt: Date,
+      usageCalculationType: String,
       usagePercentage: Number,
       usageTimeframe: String,
       usageType: String

lib/recurly/resources/ExternalProduct.js

@@ -0,0 +1,37 @@
+/* istanbul ignore file */
+/**
+ * This file is automatically created by Recurly's OpenAPI generation process
+ * and thus any edits you make by hand will be lost. If you wish to make a
+ * change to this file, please create a Github issue explaining the changes you
+ * need and we will usher them to the appropriate places.
+ */
+'use strict'
+
+const Resource = require('../Resource')
+
+/**
+ * ExternalProduct
+ * @typedef {Object} ExternalProduct
+ * @prop {Date} createdAt - When the external product was created in Recurly.
+ * @prop {Array.<ExternalProductReferenceMini>} externalProductReferences - List of external product references of the external product.
+ * @prop {string} id - System-generated unique identifier for an external product ID, e.g. `e28zov4fw0v2`.
+ * @prop {string} name - Name to identify the external product in Recurly.
+ * @prop {string} object - Object type
+ * @prop {PlanMini} plan - Just the important parts.
+ * @prop {Date} updatedAt - When the external product was updated in Recurly.
+ */
+class ExternalProduct extends Resource {
+  static getSchema () {
+    return {
+      createdAt: Date,
+      externalProductReferences: ['ExternalProductReferenceMini'],
+      id: String,
+      name: String,
+      object: String,
+      plan: 'PlanMini',
+      updatedAt: Date
+    }
+  }
+}
+
+module.exports = ExternalProduct

lib/recurly/resources/ExternalProductReferenceMini.js

@@ -0,0 +1,35 @@
+/* istanbul ignore file */
+/**
+ * This file is automatically created by Recurly's OpenAPI generation process
+ * and thus any edits you make by hand will be lost. If you wish to make a
+ * change to this file, please create a Github issue explaining the changes you
+ * need and we will usher them to the appropriate places.
+ */
+'use strict'
+
+const Resource = require('../Resource')
+
+/**
+ * ExternalProductReferenceMini
+ * @typedef {Object} ExternalProductReferenceMini
+ * @prop {Date} createdAt - When the external product was created in Recurly.
+ * @prop {string} externalConnectionType - Source connection platform.
+ * @prop {string} id - System-generated unique identifier for an external product ID, e.g. `e28zov4fw0v2`.
+ * @prop {string} object - object
+ * @prop {string} referenceCode - A code which associates the external product to a corresponding object or resource in an external platform like the Apple App Store or Google Play Store.
+ * @prop {Date} updatedAt - When the external product was updated in Recurly.
+ */
+class ExternalProductReferenceMini extends Resource {
+  static getSchema () {
+    return {
+      createdAt: Date,
+      externalConnectionType: String,
+      id: String,
+      object: String,
+      referenceCode: String,
+      updatedAt: Date
+    }
+  }
+}
+
+module.exports = ExternalProductReferenceMini

lib/recurly/resources/ExternalResourceMini.js

@@ -0,0 +1,29 @@
+/* istanbul ignore file */
+/**
+ * This file is automatically created by Recurly's OpenAPI generation process
+ * and thus any edits you make by hand will be lost. If you wish to make a
+ * change to this file, please create a Github issue explaining the changes you
+ * need and we will usher them to the appropriate places.
+ */
+'use strict'
+
+const Resource = require('../Resource')
+
+/**
+ * ExternalResourceMini
+ * @typedef {Object} ExternalResourceMini
+ * @prop {string} externalObjectReference - Identifier or URL reference where the resource is canonically available in the external platform.
+ * @prop {string} id - System-generated unique identifier for an external resource ID, e.g. `e28zov4fw0v2`.
+ * @prop {string} object - Object type
+ */
+class ExternalResourceMini extends Resource {
+  static getSchema () {
+    return {
+      externalObjectReference: String,
+      id: String,
+      object: String
+    }
+  }
+}
+
+module.exports = ExternalResourceMini

lib/recurly/resources/ExternalSubscription.js

@@ -0,0 +1,49 @@
+/* istanbul ignore file */
+/**
+ * This file is automatically created by Recurly's OpenAPI generation process
+ * and thus any edits you make by hand will be lost. If you wish to make a
+ * change to this file, please create a Github issue explaining the changes you
+ * need and we will usher them to the appropriate places.
+ */
+'use strict'
+
+const Resource = require('../Resource')
+
+/**
+ * ExternalSubscription
+ * @typedef {Object} ExternalSubscription
+ * @prop {AccountMini} account - Account mini details
+ * @prop {Date} activatedAt - When the external subscription was activated in the external platform.
+ * @prop {string} appIdentifier - Identifier of the app that generated the external subscription.
+ * @prop {boolean} autoRenew - An indication of whether or not the external subscription will auto-renew at the expiration date.
+ * @prop {Date} createdAt - When the external subscription was created in Recurly.
+ * @prop {Date} expiresAt - When the external subscription expires in the external platform.
+ * @prop {ExternalProductReferenceMini} externalProductReference - External Product Reference details
+ * @prop {ExternalResourceMini} externalResource - External Resource mini details
+ * @prop {string} id - System-generated unique identifier for an external subscription ID, e.g. `e28zov4fw0v2`.
+ * @prop {Date} lastPurchased - When a new billing event occurred on the external subscription in conjunction with a recent billing period, reactivation or upgrade/downgrade.
+ * @prop {string} object - Object type
+ * @prop {number} quantity - An indication of the quantity of a subscribed item's quantity.
+ * @prop {Date} updatedAt - When the external subscription was updated in Recurly.
+ */
+class ExternalSubscription extends Resource {
+  static getSchema () {
+    return {
+      account: 'AccountMini',
+      activatedAt: Date,
+      appIdentifier: String,
+      autoRenew: Boolean,
+      createdAt: Date,
+      expiresAt: Date,
+      externalProductReference: 'ExternalProductReferenceMini',
+      externalResource: 'ExternalResourceMini',
+      id: String,
+      lastPurchased: Date,
+      object: String,
+      quantity: Number,
+      updatedAt: Date
+    }
+  }
+}
+
+module.exports = ExternalSubscription

lib/recurly/resources/Plan.js

@@ -20,6 +20,7 @@ const Resource = require('../Resource')
  * @prop {string} code - Unique code to identify the plan. This is used in Hosted Payment Page URLs and in the invoice exports.
  * @prop {Date} createdAt - Created at
  * @prop {Array.<PlanPricing>} currencies - Pricing
+ * @prop {Array.<CustomField>} customFields - The custom fields will only be altered when they are included in a request. Sending an empty array will not remove any existing values. To remove a field send the name with a null or empty value.
  * @prop {Date} deletedAt - Deleted at
  * @prop {string} description - Optional description, not displayed.
  * @prop {string} dunningCampaignId - Unique ID to identify a dunning campaign. Used to specify if a non-default dunning campaign should be assigned to this plan. For sites without multiple dunning campaigns enabled, the default dunning campaign will always be used.
@@ -54,6 +55,7 @@ class Plan extends Resource {
       code: String,
       createdAt: Date,
       currencies: ['PlanPricing'],
+      customFields: ['CustomField'],
       deletedAt: Date,
       description: String,
       dunningCampaignId: String,

lib/recurly/resources/SubscriptionAddOn.js

@@ -22,11 +22,12 @@ const Resource = require('../Resource')
  * @prop {number} quantity - Add-on quantity
  * @prop {string} revenueScheduleType - Revenue schedule type
  * @prop {string} subscriptionId - Subscription ID
- * @prop {string} tierType - The pricing model for the add-on.  For more information, [click here](https://docs.recurly.com/docs/billing-models#section-quantity-based). See our [Guide](https://developers.recurly.com/guides/item-addon-guide.html) for an overview of how to configure quantity-based pricing models.
+ * @prop {string} tierType - The pricing model for the add-on.  For more information, [click here](https://docs.recurly.com/docs/billing-models#section-quantity-based). See our [Guide](https://recurly.com/developers/guides/item-addon-guide.html) for an overview of how to configure quantity-based pricing models.
  * @prop {Array.<SubscriptionAddOnTier>} tiers - If tiers are provided in the request, all existing tiers on the Subscription Add-on will be removed and replaced by the tiers in the request. If add_on.tier_type is tiered or volume and add_on.usage_type is percentage use percentage_tiers instead.  There must be one tier without an `ending_quantity` value which represents the final tier.
  * @prop {number} unitAmount - Supports up to 2 decimal places.
  * @prop {string} unitAmountDecimal - Supports up to 9 decimal places.
  * @prop {Date} updatedAt - Updated at
+ * @prop {string} usageCalculationType - The type of calculation to be employed for an add-on.  Cumulative billing will sum all usage records created in the current billing cycle.  Last-in-period billing will apply only the most recent usage record in the billing period.  If no value is specified, cumulative billing will be used.
  * @prop {number} usagePercentage - The percentage taken of the monetary amount of usage tracked. This can be up to 4 decimal places. A value between 0.0 and 100.0. Required if add_on_type is usage and usage_type is percentage.
  * @prop {string} usageTimeframe - The time at which usage totals are reset for billing purposes.
  */
@@ -48,6 +49,7 @@ class SubscriptionAddOn extends Resource {
       unitAmount: Number,
       unitAmountDecimal: String,
       updatedAt: Date,
+      usageCalculationType: String,
       usagePercentage: Number,
       usageTimeframe: String
     }