Merge branch 'master' into feature/split-payments

.github/workflows/test.yml

@@ -26,4 +26,4 @@ jobs:
         env:
           # Set the API key for the integration tests. In the future, all tests will rely on snapshots. An API key will
           # then only be required to update those snapshots. The API key can then be removed from this file.
-          API_KEY: test_4kQQbBMEFh8QAuKVaWdpKuRpVSsdVG
+          API_KEY: ${{ secrets.TEST_API_KEY }}

README.md

@@ -113,7 +113,7 @@ The `page` methods do not fit every use case. If you find yourself retrieving mu
 
 ```javascript
 // Iterate over all payments.
-for await (let payment in mollieClient.payments.iterate()) {
+for await (const payment of mollieClient.payments.iterate()) {
   // (Use break to end the loop prematurely.)
 }
 ```

src/Options.ts

@@ -1,3 +1,4 @@
+import type MaybeArray from './types/MaybeArray';
 import type Xor from './types/Xor';
 
 type Options = Xor<
@@ -17,7 +18,7 @@ type Options = Xor<
   /**
    * One or an array of version strings of the software you are using, such as `'RockenbergCommerce/3.1.12'`.
    */
-  versionStrings?: string | string[];
+  versionStrings?: MaybeArray<string>;
   /**
    * The headers set in the requests sent to the Mollie API. `Authorization`, `User-Agent`, `Accept`,
    * `Accept-Encoding`, and `Content-Type` are set by this library directly. Setting them here has no effect.

src/binders/customers/CustomersBinder.ts

@@ -2,9 +2,8 @@ import type TransformingNetworkClient from '../../communication/TransformingNetw
 import type Customer from '../../data/customers/Customer';
 import { type CustomerData } from '../../data/customers/Customer';
 import type Page from '../../data/page/Page';
-import ApiError from '../../errors/ApiError';
 import alias from '../../plumbing/alias';
-import checkId from '../../plumbing/checkId';
+import assertWellFormedId from '../../plumbing/assertWellFormedId';
 import renege from '../../plumbing/renege';
 import type Callback from '../../types/Callback';
 import Binder from '../Binder';
@@ -42,9 +41,7 @@ export default class CustomersBinder extends Binder<CustomerData, Customer> {
   public get(id: string, parameters: GetParameters, callback: Callback<Customer>): void;
   public get(id: string, parameters?: GetParameters) {
     if (renege(this, this.get, ...arguments)) return;
-    if (!checkId(id, 'customer')) {
-      throw new ApiError('The customer id is invalid');
-    }
+    assertWellFormedId(id, 'customer');
     return this.networkClient.get<CustomerData, Customer>(`${pathSegment}/${id}`, parameters);
   }
 
@@ -86,9 +83,7 @@ export default class CustomersBinder extends Binder<CustomerData, Customer> {
   public update(id: string, parameters: UpdateParameters, callback: Callback<Customer>): void;
   public update(id: string, parameters: UpdateParameters) {
     if (renege(this, this.update, ...arguments)) return;
-    if (!checkId(id, 'customer')) {
-      throw new ApiError('The customer id is invalid');
-    }
+    assertWellFormedId(id, 'customer');
     return this.networkClient.patch<CustomerData, Customer>(`${pathSegment}/${id}`, parameters);
   }
 
@@ -102,9 +97,7 @@ export default class CustomersBinder extends Binder<CustomerData, Customer> {
   public delete(id: string, parameters: DeleteParameters, callback: Callback<true>): void;
   public delete(id: string, parameters?: DeleteParameters) {
     if (renege(this, this.delete, ...arguments)) return;
-    if (!checkId(id, 'customer')) {
-      throw new ApiError('The customer id is invalid');
-    }
+    assertWellFormedId(id, 'customer');
     return this.networkClient.delete<CustomerData, true>(`${pathSegment}/${id}`, parameters);
   }
 }

src/binders/customers/mandates/CustomerMandatesBinder.ts

@@ -2,9 +2,8 @@ import type TransformingNetworkClient from '../../../communication/TransformingN
 import { type MandateData } from '../../../data/customers/mandates/data';
 import type Mandate from '../../../data/customers/mandates/Mandate';
 import type Page from '../../../data/page/Page';
-import ApiError from '../../../errors/ApiError';
 import alias from '../../../plumbing/alias';
-import checkId from '../../../plumbing/checkId';
+import assertWellFormedId from '../../../plumbing/assertWellFormedId';
 import renege from '../../../plumbing/renege';
 import type Callback from '../../../types/Callback';
 import Binder from '../../Binder';
@@ -34,9 +33,7 @@ export default class CustomerMandatesBinder extends Binder<MandateData, Mandate>
   public create(parameters: CreateParameters) {
     if (renege(this, this.create, ...arguments)) return;
     const { customerId, ...data } = parameters;
-    if (!checkId(customerId, 'customer')) {
-      throw new ApiError('The customer id is invalid');
-    }
+    assertWellFormedId(customerId, 'customer');
     return this.networkClient.post<MandateData, Mandate>(getPathSegments(customerId), data);
   }
 
@@ -50,13 +47,9 @@ export default class CustomerMandatesBinder extends Binder<MandateData, Mandate>
   public get(id: string, parameters: GetParameters, callback: Callback<Mandate>): void;
   public get(id: string, parameters: GetParameters) {
     if (renege(this, this.get, ...arguments)) return;
-    if (!checkId(id, 'mandate')) {
-      throw new ApiError('The customers_mandate id is invalid');
-    }
+    assertWellFormedId(id, 'mandate');
     const { customerId, ...query } = parameters;
-    if (!checkId(customerId, 'customer')) {
-      throw new ApiError('The customer id is invalid');
-    }
+    assertWellFormedId(customerId, 'customer');
     return this.networkClient.get<MandateData, Mandate>(`${getPathSegments(customerId)}/${id}`, query);
   }
 
@@ -73,9 +66,7 @@ export default class CustomerMandatesBinder extends Binder<MandateData, Mandate>
   public page(parameters: PageParameters) {
     if (renege(this, this.page, ...arguments)) return;
     const { customerId, ...query } = parameters;
-    if (!checkId(customerId, 'customer')) {
-      throw new ApiError('The customer id is invalid');
-    }
+    assertWellFormedId(customerId, 'customer');
     return this.networkClient.page<MandateData, Mandate>(getPathSegments(customerId), 'mandates', query).then(result => this.injectPaginationHelpers(result, this.page, parameters));
   }
 
@@ -89,9 +80,7 @@ export default class CustomerMandatesBinder extends Binder<MandateData, Mandate>
    */
   public iterate(parameters: IterateParameters) {
     const { customerId, valuesPerMinute, ...query } = parameters;
-    if (!checkId(customerId, 'customer')) {
-      throw new ApiError('The customer id is invalid');
-    }
+    assertWellFormedId(customerId, 'customer');
     return this.networkClient.iterate<MandateData, Mandate>(getPathSegments(customerId), 'mandates', query, valuesPerMinute);
   }
 
@@ -105,13 +94,9 @@ export default class CustomerMandatesBinder extends Binder<MandateData, Mandate>
   public revoke(id: string, parameters: RevokeParameters, callback: Callback<true>): void;
   public revoke(id: string, parameters: RevokeParameters) {
     if (renege(this, this.revoke, ...arguments)) return;
-    if (!checkId(id, 'mandate')) {
-      throw new ApiError('The customers_mandate id is invalid');
-    }
+    assertWellFormedId(id, 'mandate');
     const { customerId, ...context } = parameters;
-    if (!checkId(customerId, 'customer')) {
-      throw new ApiError('The customer is invalid');
-    }
+    assertWellFormedId(customerId, 'customer');
     return this.networkClient.delete<MandateData, true>(`${getPathSegments(customerId)}/${id}`, context);
   }
 }

src/binders/customers/payments/CustomerPaymentsBinder.ts

@@ -2,9 +2,8 @@ import type TransformingNetworkClient from '../../../communication/TransformingN
 import type Page from '../../../data/page/Page';
 import { type PaymentData } from '../../../data/payments/data';
 import type Payment from '../../../data/payments/Payment';
-import ApiError from '../../../errors/ApiError';
 import alias from '../../../plumbing/alias';
-import checkId from '../../../plumbing/checkId';
+import assertWellFormedId from '../../../plumbing/assertWellFormedId';
 import renege from '../../../plumbing/renege';
 import type Callback from '../../../types/Callback';
 import Binder from '../../Binder';
@@ -38,9 +37,7 @@ export default class CustomerPaymentsBinder extends Binder<PaymentData, Payment>
   public create(parameters: CreateParameters) {
     if (renege(this, this.create, ...arguments)) return;
     const { customerId, ...data } = parameters;
-    if (!checkId(customerId, 'customer')) {
-      throw new ApiError('The customer id is invalid');
-    }
+    assertWellFormedId(customerId, 'customer');
     return this.networkClient.post<PaymentData, Payment>(getPathSegments(customerId), data);
   }
 
@@ -55,9 +52,7 @@ export default class CustomerPaymentsBinder extends Binder<PaymentData, Payment>
   public page(parameters: PageParameters) {
     if (renege(this, this.page, ...arguments)) return;
     const { customerId, ...query } = parameters;
-    if (!checkId(customerId, 'customer')) {
-      throw new ApiError('The customer id is invalid');
-    }
+    assertWellFormedId(customerId, 'customer');
     return this.networkClient.page<PaymentData, Payment>(getPathSegments(customerId), 'payments', query).then(result => this.injectPaginationHelpers(result, this.page, parameters));
   }
 
@@ -69,9 +64,7 @@ export default class CustomerPaymentsBinder extends Binder<PaymentData, Payment>
    */
   public iterate(parameters: IterateParameters) {
     const { customerId, valuesPerMinute, ...query } = parameters;
-    if (!checkId(customerId, 'customer')) {
-      throw new ApiError('The customer id is invalid');
-    }
+    assertWellFormedId(customerId, 'customer');
     return this.networkClient.iterate<PaymentData, Payment>(getPathSegments(customerId), 'payments', query, valuesPerMinute);
   }
 }

src/binders/customers/payments/parameters.ts

@@ -1,5 +1,6 @@
 import { type PaymentMethod } from '../../../data/global';
 import { type PaymentData } from '../../../data/payments/data';
+import type MaybeArray from '../../../types/MaybeArray';
 import { type IdempotencyParameter, type PaginationParameters, type ThrottlingParameter } from '../../../types/parameters';
 import type PickOptional from '../../../types/PickOptional';
 
@@ -21,7 +22,7 @@ export type CreateParameters = ContextParameters &
      *
      * @see https://docs.mollie.com/reference/v2/payments-api/create-payment?path=method#parameters
      */
-    method?: PaymentMethod | PaymentMethod[];
+    method?: MaybeArray<PaymentMethod>;
   } & IdempotencyParameter;
 
 export type PageParameters = ContextParameters & PaginationParameters;

src/binders/customers/subscriptions/CustomerSubscriptionsBinder.ts

@@ -2,9 +2,8 @@ import type TransformingNetworkClient from '../../../communication/TransformingN
 import type Page from '../../../data/page/Page';
 import { type SubscriptionData } from '../../../data/subscriptions/data';
 import type Subscription from '../../../data/subscriptions/Subscription';
-import ApiError from '../../../errors/ApiError';
 import alias from '../../../plumbing/alias';
-import checkId from '../../../plumbing/checkId';
+import assertWellFormedId from '../../../plumbing/assertWellFormedId';
 import renege from '../../../plumbing/renege';
 import type Callback from '../../../types/Callback';
 import Binder from '../../Binder';
@@ -41,9 +40,7 @@ export default class CustomerSubscriptionsBinder extends Binder<SubscriptionData
   public create(parameters: CreateParameters) {
     if (renege(this, this.create, ...arguments)) return;
     const { customerId, ...data } = parameters;
-    if (!checkId(customerId, 'customer')) {
-      throw new ApiError('The customer id is invalid');
-    }
+    assertWellFormedId(customerId, 'customer');
     return this.networkClient.post<SubscriptionData, Subscription>(getPathSegments(customerId), data);
   }
 
@@ -57,13 +54,9 @@ export default class CustomerSubscriptionsBinder extends Binder<SubscriptionData
   public get(id: string, parameters: GetParameters, callback: Callback<Subscription>): void;
   public get(id: string, parameters: GetParameters) {
     if (renege(this, this.get, ...arguments)) return;
-    if (!checkId(id, 'subscription')) {
-      throw new ApiError('The subscription id is invalid');
-    }
+    assertWellFormedId(id, 'subscription');
     const { customerId, ...query } = parameters;
-    if (!checkId(customerId, 'customer')) {
-      throw new ApiError('The customer id is invalid');
-    }
+    assertWellFormedId(customerId, 'customer');
     return this.networkClient.get<SubscriptionData, Subscription>(`${getPathSegments(customerId)}/${id}`, query);
   }
 
@@ -78,9 +71,7 @@ export default class CustomerSubscriptionsBinder extends Binder<SubscriptionData
   public page(parameters: PageParameters) {
     if (renege(this, this.page, ...arguments)) return;
     const { customerId, ...query } = parameters;
-    if (!checkId(customerId, 'customer')) {
-      throw new ApiError('The customer id is invalid');
-    }
+    assertWellFormedId(customerId, 'customer');
     return this.networkClient.page<SubscriptionData, Subscription>(getPathSegments(customerId), 'subscriptions', query).then(result => this.injectPaginationHelpers(result, this.page, parameters));
   }
 
@@ -92,9 +83,7 @@ export default class CustomerSubscriptionsBinder extends Binder<SubscriptionData
    */
   public iterate(parameters: IterateParameters) {
     const { customerId, valuesPerMinute, ...query } = parameters;
-    if (!checkId(customerId, 'customer')) {
-      throw new ApiError('The customer id is invalid');
-    }
+    assertWellFormedId(customerId, 'customer');
     return this.networkClient.iterate<SubscriptionData, Subscription>(getPathSegments(customerId), 'subscriptions', query, valuesPerMinute);
   }
 
@@ -110,13 +99,9 @@ export default class CustomerSubscriptionsBinder extends Binder<SubscriptionData
   public update(id: string, parameters: UpdateParameters, callback: Callback<Subscription>): void;
   public update(id: string, parameters: UpdateParameters) {
     if (renege(this, this.update, ...arguments)) return;
-    if (!checkId(id, 'subscription')) {
-      throw new ApiError('The subscription id is invalid');
-    }
+    assertWellFormedId(id, 'subscription');
     const { customerId, ...data } = parameters;
-    if (!checkId(customerId, 'customer')) {
-      throw new ApiError('The customer is invalid');
-    }
+    assertWellFormedId(customerId, 'customer');
     return this.networkClient.patch<SubscriptionData, Subscription>(`${getPathSegments(customerId)}/${id}`, data);
   }
 
@@ -130,13 +115,9 @@ export default class CustomerSubscriptionsBinder extends Binder<SubscriptionData
   public cancel(id: string, parameters: CancelParameters, callback: Callback<Subscription>): void;
   public cancel(id: string, parameters: CancelParameters) {
     if (renege(this, this.cancel, ...arguments)) return;
-    if (!checkId(id, 'subscription')) {
-      throw new ApiError('The subscription id is invalid');
-    }
+    assertWellFormedId(id, 'subscription');
     const { customerId, ...context } = parameters;
-    if (!checkId(customerId, 'customer')) {
-      throw new ApiError('The customer is invalid');
-    }
+    assertWellFormedId(customerId, 'customer');
     return this.networkClient.delete<SubscriptionData, Subscription>(`${getPathSegments(customerId)}/${id}`, context);
   }
 }

src/binders/methods/parameters.ts

@@ -1,5 +1,6 @@
 import { type Amount, type Locale, type SequenceType } from '../../data/global';
 import { type MethodInclude } from '../../data/methods/data';
+import type MaybeArray from '../../types/MaybeArray';
 
 export interface GetParameters {
   /**
@@ -10,7 +11,7 @@ export interface GetParameters {
    * @see https://docs.mollie.com/reference/v2/methods-api/get-method?path=locale#parameters
    */
   locale?: Locale;
-  include?: MethodInclude[] | MethodInclude;
+  include?: MaybeArray<MethodInclude>;
   profileId?: string;
   testmode?: boolean;
   /**
@@ -103,7 +104,7 @@ export interface ListParameters {
    * @see https://docs.mollie.com/reference/v2/methods-api/list-methods?path=orderLineCategories#parameters
    */
   orderLineCategories?: string[];
-  include?: MethodInclude[] | MethodInclude;
+  include?: MaybeArray<MethodInclude>;
   profileId?: string;
   testmode?: boolean;
 }

src/binders/orders/OrdersBinder.ts

@@ -2,8 +2,7 @@ import type TransformingNetworkClient from '../../communication/TransformingNetw
 import type Page from '../../data/page/Page';
 import { type OrderData } from '../../data/orders/data';
 import type Order from '../../data/orders/Order';
-import ApiError from '../../errors/ApiError';
-import checkId from '../../plumbing/checkId';
+import assertWellFormedId from '../../plumbing/assertWellFormedId';
 import renege from '../../plumbing/renege';
 import type Callback from '../../types/Callback';
 import Binder from '../Binder';
@@ -73,9 +72,7 @@ export default class OrdersBinder extends Binder<OrderData, Order> {
   public get(id: string, parameters: GetParameters, callback: Callback<Order>): void;
   public get(id: string, parameters?: GetParameters) {
     if (renege(this, this.get, ...arguments)) return;
-    if (!checkId(id, 'order')) {
-      throw new ApiError('The order id is invalid');
-    }
+    assertWellFormedId(id, 'order');
     return this.networkClient.get<OrderData, Order>(`${pathSegment}/${id}`, parameters);
   }
 
@@ -120,9 +117,7 @@ export default class OrdersBinder extends Binder<OrderData, Order> {
   public update(id: string, parameters: UpdateParameters, callback: Callback<Order>): void;
   public update(id: string, parameters: UpdateParameters) {
     if (renege(this, this.update, ...arguments)) return;
-    if (!checkId(id, 'order')) {
-      throw new ApiError('The order id is invalid');
-    }
+    assertWellFormedId(id, 'order');
     return this.networkClient.patch<OrderData, Order>(`${pathSegment}/${id}`, parameters);
   }
 
@@ -148,9 +143,7 @@ export default class OrdersBinder extends Binder<OrderData, Order> {
   public cancel(id: string, parameters: CancelParameters, callback: Callback<Order>): void;
   public cancel(id: string, parameters?: CancelParameters) {
     if (renege(this, this.cancel, ...arguments)) return;
-    if (!checkId(id, 'order')) {
-      throw new ApiError('The order id is invalid');
-    }
+    assertWellFormedId(id, 'order');
     return this.networkClient.delete<OrderData, Order>(`${pathSegment}/${id}`, parameters);
   }
 }