feat(api): add get subscription payments method

Author: stfsy

README_SUBSCRIPTION_API.md

@@ -11,6 +11,7 @@ Low level wrapper for Paddle API.
     - [List all subscriptions](#list-all-subscriptions)
     - [Get subscription plan](#get-subscription-plan)
     - [List all subscription plans](#list-all-subscription-plans)
+    - [List all subscription payments](#list-all-subscription-payments)
     - [Update subscription plan](#update-subscription-plan)
     - [Update subscription post code](#update-subscription-post-code)
     - [Cancel subscription](#cancel-subscription)
@@ -211,6 +212,25 @@ const plans = await paddleApi.listPlans()
 
 [API reference](https://developer.paddle.com/api-reference/a835554495295-list-plans)
 
+### List all subscription payments
+```js
+const plans = await paddleApi.getSubscriptionPayments({ subscription_id: 12345 }, { plan: 4815, from: '2022-04-01', to: '2023-01-01' })
+// [
+//   {
+//     "id": 8936,
+//     "subscription_id": 2746,
+//     "amount": 1,
+//     "currency": "USD",
+//     "payout_date": "2015-10-15",
+//     "is_paid": 0,
+//     "is_one_off_charge": false,
+//     "receipt_url": "https://my.paddle.com/receipt/469214-8936/1940881-chrea0eb34164b5-f0d6553bdf"
+//   }
+// ]
+```
+
+[API reference](https://developer.paddle.com/api-reference/80462f27b2011-list-payments)
+
 
 ### Update subscription plan
 ```js

lib/paddle/api.js

@@ -137,6 +137,51 @@ module.exports = class {
             })
     }
 
+    /**
+     * @typedef GetSubscriptionPaymentsOptions
+     * @property {string} [plan=null] subscription plan id
+     * @property {string} [from=null] filter payments starting after the date specified (date in format YYYY-MM-DD)
+     * @property {string} [to=null] filter payments ending the day before the date specified (date in format YYYY-MM-DD)
+     */
+
+    /**
+     * @typedef SubscriptionPayment
+     * @property {string} id
+     * @property {string} subscription_id
+     * @property {string} amount
+     * @property {string} currency
+     * @property {string} payout_date format YYYY-MM-DD
+     * @property {number} is_paid 1 = true, 0 = false
+     * @property {boolean} is_one_off_charge
+     * @property {string} receipt_url
+     */
+
+    /**
+     * @param {Object} subscription target subscription object 
+     * @param {GetSubscriptionPaymentsOptions} [subscription=undefined] the target subscription object
+     * @returns {Array.<SubscriptionPayment>}
+     */
+    async getSubscriptionPayments({ subscription_id }, { plan, from, to } = {}) {
+        const form = {
+            vendor_id: this._vendorId,
+            vendor_auth_code: this._authCode,
+            subscription_id
+        }
+
+        if (plan) {
+            form.plan = plan
+        }
+        if (from) {
+            form.from = from
+        }
+        if (to) {
+            form.to = to
+        }
+        return this._returnResponseIf200(this._request(this._vendorsBaseUrl + PATH_LIST_PAYMENTS, {
+            form
+        }))
+    }
+
     /**
        * 
        * @param {Object} checkout the target checkout object

test-e2e/spec/api.spec.js

@@ -2,6 +2,9 @@
 
 const { test, expect } = require('@playwright/test')
 
+/**
+ * @type {import('../../lib/paddle/api.js')}
+ */
 let api
 
 test.beforeAll(async () => {
@@ -29,6 +32,31 @@ test('list all plans', async () => {
     expect(subs.length).toBeGreaterThanOrEqual(2)
 })
 
+test('list all subscription payments', async () => {
+    const payments = await api.getSubscriptionPayments({ subscription_id: '399236' })
+    expect(payments).toHaveLength(1)
+})
+
+test('filters subscription payments by plan (correct plan)', async () => {
+    const payments = await api.getSubscriptionPayments({ subscription_id: '399236' }, { plan: '33590' })
+    expect(payments).toHaveLength(1)
+})
+
+test('filters subscription payments starting after', async () => {
+    const payments = await api.getSubscriptionPayments({ subscription_id: '399236' }, { from: '2030-01-01' })
+    expect(payments).toHaveLength(0)
+})
+
+test('filters subscription payments starting before 2030', async () => {
+    const payments = await api.getSubscriptionPayments({ subscription_id: '399236' }, { to: '2030-01-01' })
+    expect(payments).toHaveLength(1)
+})
+
+test('filters subscription payments starting before 2020', async () => {
+    const payments = await api.getSubscriptionPayments({ subscription_id: '399236' }, { to: '2020-01-01' })
+    expect(payments).toHaveLength(0)
+})
+
 test('get plan by id', async () => {
     const subs = await api.getPlan({ plan_id: 33590 })
     expect(subs.length).toEqual(1)