Merge branch 'main' into feature/captures

CHANGELOG.md

@@ -3,7 +3,25 @@
 
 ### Changelog
 
-All notable changes to this project will be documented in this file.
+Please see [the migration guide](MIGRATION.md) for guidance about updating to a newer major version.
+
+### v4.0.0 - 2024-09-19
+  - Replace Axios dependency in favour of [fetch](https://developer.mozilla.org/docs/Web/API/fetch) ([#358](https://github.com/mollie/mollie-api-node/pull/358))
+  - Add `cancelUrl` and `getDashboardUrl` to payments and orders ([#327](https://github.com/mollie/mollie-api-node/pull/327)/[#373](https://github.com/mollie/mollie-api-node/pull/373))
+  - Add `status` and `issuers` to methods and update `pricing` ([#335](https://github.com/mollie/mollie-api-node/pull/335)/[#374](https://github.com/mollie/mollie-api-node/pull/374))
+  - Update and export `PaymentInclude` ([#370](https://github.com/mollie/mollie-api-node/pull/370))
+  - Update payment methods ([#376](https://github.com/mollie/mollie-api-node/pull/376))
+  - Change type of `metadata` (from `any`) to `unknown` ([#367](https://github.com/mollie/mollie-api-node/pull/367))
+  - Change return type of functions to plain arrays or iterators, depending on whether the represented list is paginated ([#322](https://github.com/mollie/mollie-api-node/pull/322))
+  - Bump Node.js requirement to 14
+  - Remove snake case properties, e.g. `customers_payments` ([#314](https://github.com/mollie/mollie-api-node/pull/314)/[#353](https://github.com/mollie/mollie-api-node/pull/353))
+  - Remove endpoint aliases, e.g. `delete` intead of `cancel` ([#315](https://github.com/mollie/mollie-api-node/pull/315)/[#353](https://github.com/mollie/mollie-api-node/pull/353))
+  - Remove predictable helper functions ([#364](https://github.com/mollie/mollie-api-node/pull/364))
+  - Remove fields from `ApiError` ([#363](https://github.com/mollie/mollie-api-node/pull/363))
+  - Remove `count` from pages ([#365](https://github.com/mollie/mollie-api-node/pull/365))
+  - Remove `withParent` ([#323](https://github.com/mollie/mollie-api-node/pull/323))
+  - Remove `toPlainObject` ([#362](https://github.com/mollie/mollie-api-node/pull/362))
+  - Remove `Object.entries` polyfill ([#352](https://github.com/mollie/mollie-api-node/pull/352))
 
 ### v3.7.0 - 2023-03-08
 

MIGRATION.md

@@ -1,4 +1,120 @@
-# Migrating from v2.3.2 to v3.0.0
+# Migrating from v3.×.× to v4.0.0
+
+## Raised Node.js requirement
+
+Node.js 14+ is officially supported, although we believe Node.js 8+ should work.
+
+## Removed `withParent`
+
+`withParent` has been removed, eliminating state from the client:
+```diff
+- const payments = mollieClient.customerPayments.withParent(customer).iterate();
++ const payments = mollieClient.customerPayments.iterate({ customerId: customer.id });
+  for await (const payment of payments) {
+    …
+  }
+```
+
+## Removed snake case properties (e.g. `payments_refunds`)
+
+Snake case properties have been removed in favour of camel case ones. Please use `paymentRefunds` instead of `payments_refunds`, `orderShipments` instead of `orders_shipments`, et cetera:
+```diff
+- mollieClient.customers_subscriptions.get('sub_PCN3U3U27K', { customerId: 'cst_pzhEvnttJ2' })
++ mollieClient.customerSubscriptions.get('sub_PCN3U3U27K', { customerId: 'cst_pzhEvnttJ2' });
+```
+
+## Removed endpoint aliases (e.g. `payments.delete`)
+
+Endpoint aliases have been removed. Please use `mollieClient.payments.cancel` instead of `mollieClient.payments.delete`, `mollieClient.refunds.page` instead of `mollieClient.refunds.list`, et cetera:
+```diff
+- mollieClient.subscriptions.list({ limit: 10 })
++ mollieClient.subscriptions.page({ limit: 10 })
+```
+
+## Removed predictable helper functions
+
+Helper functions which do not provide a significantly simpler API have been removed:
+```diff
+- if (payment.isOpen()) {
++ if (payment.status == PaymentStatus.open) {
+```
+```diff
+- if (payment.hasSequenceTypeFirst()) {
++ if (payment.sequenceType == SequenceType.first)
+```
+
+## Removed functions from `ApiError`
+
+`getMessage`, `getField`, `getStatusCode` have been removed from `ApiError`. Please use `message`, `field`, and `statusCode` instead:
+```diff
+  try {
+    const payment = await mollieClient.payments.get(…);
+  } catch (error) {
+-   console.warn(error.getMessage())
++   console.warn(error.message)
+  }
+```
+
+## Removed Giropay and SOFORT
+
+[Giropay](https://help.mollie.com/hc/en-us/articles/19745480480786-Giropay-Depreciation-FAQ) and [SOFORT](https://help.mollie.com/hc/en-us/articles/20904206772626-SOFORT-Deprecation-30-September-2024) have been deprecated, and removed from the client. Please update your code accordingly.
+
+## Changed type of `metadata` (from `any`) to `unknown`
+
+The `metadata` property is now typed as `unknown`. Please check its type at runtime, or use `as any` to opt in to type issues.
+
+This is part of a larger movement in the TypeScript universe to reduce usage of the `any` type. See [microsoft/TypeScript#41016](https://github.com/microsoft/TypeScript/issues/41016).
+
+## Removed `count`
+
+The `count` property has been removed from pages, please use `length` instead:
+```diff
+- mollieClient.payments.page({ limit: 10 }).count
++ mollieClient.payments.page({ limit: 10 }).length
+```
+
+## Changed return type of list functions
+
+The return type of list functions now reflects whether the underlying endpoint is paginated. The following functions return (plain) arrays:
+
+ * `mollieClient.methods.list`
+ * `mollieClient.orderShipments.list`
+ * `mollieClient.permissions.list`
+
+The following functions return iterators:
+
+ * `customer.getMandates()`
+ * `customer.getSubscriptions()`
+ * `customer.getPayments()`
+ * `order.getRefunds()`
+ * `payment.getRefunds()`
+ * `payment.getChargebacks()`
+ * `payment.getCaptures()`
+ * `profile.getChargebacks()`
+ * `profile.getPayments()`
+ * `profile.getRefunds()`
+ * `subscription.getPayments()`
+
+## Removed `toPlainObject`
+
+`toPlainObject` has been removed. The appropriate alternative depends on your motivation to use the now-removed function.
+
+## Removed Axios-specific options
+
+Previously, it was possible to provide options to Axios through `createMollieClient`. The client no longer uses Axios. The following options no longer have any effect:
+
+ * `adapter`
+ * `proxy`
+ * `socketPath`
+ * `timeout`
+
+Please [create an issue](https://github.com/mollie/mollie-api-node/issues/new) if you rely on such an option.
+
+## Note: network error messages may have changed
+
+It is possible that network issues produce different values for the `message` property of the produced errors compared to previous versions of the client. If your integration relies on `message`, please update your error handling code accordingly.
+
+# Migrating from v2.×.× to v3.0.0
 
 ## Initialization
 
@@ -60,7 +176,7 @@ The alternative using JavaScript modules would be to replace the first line of t
 import createMollieClient, { PaymentMethod } from '@mollie/api-client';
 ```
 
-# Migrating from v1.x to v2.0
+# Migrating from v1.×.× to v2.0.0
 
 Version 2.x of the Node client uses the v2 Mollie API. Please refer to  [Migrating from v1 to v2](https://docs.mollie.com/migrating-v1-to-v2) for a general overview of the changes introduced by the new Mollie API.
 

README.md

@@ -7,7 +7,7 @@
 
 # About
 
-[Mollie](https://www.mollie.com/) builds payment products, commerce solutions and APIs that let you accept online and mobile payments, for small online stores and Fortune 500s alike. Accepting [Credit Card][credit-card], [Apple Pay][apple-pay], [PayPal][paypal], [Klarna: Pay now][klarna-pay-now], [Klarna: Pay later][klarna-pay-later], [Klarna: Slice it][klarna-slice-it], [iDeal][ideal], [vouchers][meal-eco-gift-vouchers], [SEPA Bank Transfer][bank-transfer], [SEPA Direct Debit][direct-debit], [SOFORT banking][sofort], [Bancontact][bancontact], [Cartes Bancaires][cartes-bancaires], [EPS][eps], [PostePay][postepay], [Giropay][giropay], [KBC Payment Button][kbc-cbc], [Belfius Pay Button][belfius], [paysafecard][paysafecard], [gift cards][gift-cards], and [Przelewy24][przelewy24] online payments without fixed monthly costs or any punishing registration procedures. Just use the Mollie API to receive payments directly on your website or easily refund transactions to your customers.
+[Mollie](https://www.mollie.com/) builds payment products, commerce solutions and APIs that let you accept online and mobile payments, for small online stores and Fortune 500s alike. Accepting [credit and debit card][credit-card] ([Cartes Bancaires][cartes-bancaires], [PostePay][postepay]), [Alma][alma], [Apple Pay][apple-pay], [BACS Direct Debit][bacs], [BANCOMAT Pay][bancomat-pay], [Bancontact][bancontact], [SEPA Bank Transfer][bank-transfer], [Belfius Pay Button][belfius], [Billie][billie], [BLIK][blik], [SEPA Direct Debit][direct-debit], [EPS][eps], [iDEAL][ideal] ([in3][ideal-in3]), [KBC Payment Button][kbc-cbc], [Klarna][klarna] (Pay Later, Pay Now, Pay in 3, Financing), [PayPal][paypal], [paysafecard][paysafecard], [Przelewy24][przelewy24], [Riverty][riverty], [Satispay][satispay], [Trustly][trustly], [TWINT][twint], [eco- gift- and meal vouchers][meal-eco-gift-vouchers] and [gift cards][gift-cards] online payments without fixed monthly costs or any punishing registration procedures. Just use the Mollie API to receive payments directly on your website or easily refund transactions to your customers.
 
 ### A note on use outside of Node.js
 
@@ -133,7 +133,7 @@ For a deep dive in how our systems function, we refer to [our excellent guides](
 
 ## API reference
 
-This library is a wrapper around our Mollie API. Some more specific details are better explained in [our API reference](https://docs.mollie.com/reference/v2/), and you can also get a better understanding of how the requests look under the hood.
+This library is a wrapper around our Mollie API. Some more specific details are better explained in [our API reference](https://docs.mollie.com/reference/), and you can also get a better understanding of how the requests look under the hood.
 
 ## Migrating
 
@@ -147,24 +147,31 @@ Want to help us make our API client even better? We take [pull requests](https:/
 
 [New BSD (Berkeley Software Distribution) License](https://opensource.org/licenses/BSD-3-Clause). Copyright 2013-2021, Mollie B.V.
 
-[credit-card]: https://www.mollie.com/payments/credit-card
+[alma]: https://www.mollie.com/payments/alma
 [apple-pay]: https://www.mollie.com/payments/apple-pay
-[paypal]: https://www.mollie.com/payments/paypal
-[klarna-pay-now]: https://www.mollie.com/payments/klarna-pay-now
-[klarna-pay-later]: https://www.mollie.com/payments/klarna-pay-later
-[klarna-slice-it]: https://www.mollie.com/payments/klarna-slice-it
-[ideal]: https://www.mollie.com/payments/ideal
-[meal-eco-gift-vouchers]: https://www.mollie.com/payments/meal-eco-gift-vouchers
-[bank-transfer]: https://www.mollie.com/payments/bank-transfer
-[direct-debit]: https://www.mollie.com/payments/direct-debit
-[sofort]: https://www.mollie.com/payments/sofort
+[bacs]: https://www.mollie.com/payments/bacs
+[bancomat-pay]: https://www.mollie.com/payments/bancomat-pay
 [bancontact]: https://www.mollie.com/payments/bancontact
+[bank-transfer]: https://www.mollie.com/payments/bank-transfer
+[belfius]: https://www.mollie.com/payments/belfius
+[billie]: https://www.mollie.com/payments/billie
+[blik]: https://www.mollie.com/payments/blik
 [cartes-bancaires]: https://www.mollie.com/payments/cartes-bancaires
+[credit-card]: https://www.mollie.com/payments/credit-card
+[direct-debit]: https://www.mollie.com/payments/direct-debit
 [eps]: https://www.mollie.com/payments/eps
-[postepay]: https://www.mollie.com/payments/postepay
-[giropay]: https://www.mollie.com/payments/giropay
+[gift-cards]: https://www.mollie.com/payments/gift-cards
+[ideal]: https://www.mollie.com/payments/ideal
+[ideal-in3]: https://www.mollie.com/payments/ideal-in3
 [kbc-cbc]: https://www.mollie.com/payments/kbc-cbc
-[belfius]: https://www.mollie.com/payments/belfius
+[klarna]: https://www.mollie.com/payments/klarna
+[meal-eco-gift-vouchers]: https://www.mollie.com/payments/meal-eco-gift-vouchers
+[mybank]: https://www.mollie.com/payments/mybank
+[paypal]: https://www.mollie.com/payments/paypal
 [paysafecard]: https://www.mollie.com/payments/paysafecard
-[gift-cards]: https://www.mollie.com/payments/gift-cards
+[postepay]: https://www.mollie.com/payments/postepay
 [przelewy24]: https://www.mollie.com/payments/przelewy24
+[riverty]: https://www.mollie.com/payments/riverty
+[satispay]: https://www.mollie.com/payments/satispay
+[trustly]: https://www.mollie.com/payments/trustly
+[twint]: https://www.mollie.com/payments/twint

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mollie/api-client",
-  "version": "3.7.0",
+  "version": "4.0.0",
   "license": "BSD-3-Clause",
   "description": "Official Mollie API client for Node",
   "repository": {
@@ -20,7 +20,7 @@
   "main": "dist/mollie.cjs.js",
   "module": "dist/mollie.esm.js",
   "jsnext:main": "dist/mollie.esm.js",
-  "types": "dist/types/src/types.d.ts",
+  "types": "dist/types/types.d.ts",
   "engines": {
     "node": ">=8"
   },
@@ -41,6 +41,7 @@
     "lint": "yarn lint:eslint:fix && yarn lint:prettier"
   },
   "dependencies": {
+    "@types/node-fetch": "^2.6.11",
     "node-fetch": "^2.7.0",
     "ruply": "^1.0.1"
   },
@@ -51,7 +52,6 @@
     "@mollie/eslint-config-typescript": "^1.6.5",
     "@types/jest": "^29.5.12",
     "@types/node": "^22.5.4",
-    "@types/node-fetch": "^2.6.11",
     "babel-jest": "^29.7.0",
     "commitizen": "^4.3.0",
     "cz-conventional-changelog": "^3.3.0",

src/createMollieClient.ts

@@ -187,12 +187,12 @@ export default function createMollieClient(options: Options) {
 export { createMollieClient };
 
 export { ApiMode, Locale, PaymentMethod, HistoricPaymentMethod, SequenceType } from './data/global';
-export { CaptureInclude, CaptureStatus } from './data/payments/captures/data';
+export { CaptureStatus, CaptureInclude } from './data/payments/captures/data';
 export { MandateMethod, MandateStatus } from './data/customers/mandates/data';
 export { MethodImageSize, MethodInclude } from './data/methods/data';
 export { OrderEmbed, OrderStatus } from './data/orders/data';
 export { OrderLineType } from './data/orders/orderlines/OrderLine';
-export { PaymentEmbed, PaymentStatus, CaptureMethod } from './data/payments/data';
+export { PaymentEmbed, PaymentInclude, PaymentStatus, CaptureMethod } from './data/payments/data';
 export { RefundEmbed, RefundStatus } from './data/refunds/data';
 export { SubscriptionStatus } from './data/subscriptions/data';
 export { ProfileStatus } from './data/profiles/data';

src/data/global.ts

@@ -23,32 +23,42 @@ export enum Locale {
 }
 
 export enum PaymentMethod {
+  alma = 'alma',
   applepay = 'applepay',
+  bacs = 'bacs',
+  bancomatpay = 'bancomatpay',
   bancontact = 'bancontact',
   banktransfer = 'banktransfer',
   belfius = 'belfius',
+  billie = 'billie',
+  blik = 'blik',
   creditcard = 'creditcard',
   directdebit = 'directdebit',
   eps = 'eps',
   giftcard = 'giftcard',
-  giropay = 'giropay',
   ideal = 'ideal',
   in3 = 'in3',
   kbc = 'kbc',
+  klarna = 'klarna',
   klarnapaylater = 'klarnapaylater',
   klarnapaynow = 'klarnapaynow',
   klarnasliceit = 'klarnasliceit',
   mybank = 'mybank',
   paypal = 'paypal',
   paysafecard = 'paysafecard',
   przelewy24 = 'przelewy24',
-  sofort = 'sofort',
+  riverty = 'riverty',
+  satispay = 'satispay',
+  trustly = 'trustly',
+  twint = 'twint',
   voucher = 'voucher',
 }
 
 export enum HistoricPaymentMethod {
   bitcoin = 'bitcoin',
   inghomepay = 'inghomepay',
+  giropay = 'giropay',
+  sofort = 'sofort',
 }
 
 export enum ApiMode {

src/data/methods/data.ts

@@ -28,11 +28,18 @@ export interface MethodData extends Model<'method', PaymentMethodEnum> {
    */
   image: Image;
   /**
-   * Pricing set of the payment method what will be include if you add the parameter.
+   * Array of objects describing the pricing configuration applicable for this payment method on your account.
    *
    * @see https://docs.mollie.com/reference/v2/methods-api/get-method?path=pricing#response
    */
-  pricing: MethodPricing;
+  pricing?: MethodPricing[];
+  /**
+   * Array of objects for each 'issuer' that is available for this payment method. Only relevant for iDEAL, KBC/CBC,
+   * gift cards, and vouchers.
+   *
+   * @see https://docs.mollie.com/reference/v2/methods-api/get-method?path=pricing#response
+   */
+  issuers?: MethodIssuers[];
   /**
    * An object with several URL objects relevant to the payment method. Every URL object will contain an `href` and a `type` field.
    *
@@ -93,3 +100,10 @@ export interface MethodPricing {
   variable: string;
   feeRegion: FeeRegion;
 }
+
+export interface MethodIssuers {
+  resource: string;
+  id: string;
+  name: string;
+  image: Image;
+}

src/data/orders/OrderHelper.ts

@@ -98,6 +98,16 @@ export default class OrderHelper extends Helper<OrderData, Order> {
     return this.links.checkout.href;
   }
 
+  /**
+   * Returns the direct link to the order in the Mollie Dashboard.
+   *
+   * @see https://docs.mollie.com/reference/v2/orders-api/get-order?path=_links/dashboard#response
+   * @since 4.0.0
+   */
+  public getDashboardUrl(): string {
+    return this.links.dashboard.href;
+  }
+
   /**
    * Returns all payments created for the order.
    *

src/data/orders/data.ts

@@ -202,6 +202,12 @@ export interface OrderLinks extends Links {
    * @see https://docs.mollie.com/reference/v2/orders-api/get-order?path=_links/checkout#response
    */
   checkout?: Url;
+  /**
+   * Direct link to the order in the Mollie Dashboard.
+   *
+   * @see https://docs.mollie.com/reference/v2/orders-api/get-order?path=_links/dashboard#response
+   */
+  dashboard: Url;
 }
 
 export enum OrderStatus {

src/data/payments/PaymentHelper.ts

@@ -58,6 +58,16 @@ export default class PaymentHelper extends Helper<PaymentData, Payment> {
     return this.links.checkout?.href ?? null;
   }
 
+  /**
+   * Returns the direct link to the payment in the Mollie Dashboard.
+   *
+   * @see https://docs.mollie.com/reference/v2/payments-api/get-payment?path=_links/dashboard#response
+   * @since 4.0.0
+   */
+  public getDashboardUrl(): string {
+    return this.links.dashboard.href;
+  }
+
   public canBeRefunded(this: PaymentData): boolean {
     return this.amountRemaining != undefined;
   }