From e7db5e5bb559f82687dd9ff606ca824de6dbd73b Mon Sep 17 00:00:00 2001 From: "Pimm \"de Chinchilla\" Hogeling" Date: Fri, 6 Sep 2024 16:19:47 +0200 Subject: [PATCH 1/6] Update changelog for v4.0.0. --- CHANGELOG.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2c1b7d97..c8220e0a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file. +### v4.0.0 - 2024-09-16 + - 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)) + - 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 - Update APIs ([#279](https://github.com/mollie/mollie-api-node/pull/279)/[#285](https://github.com/mollie/mollie-api-node/pull/285)/[#292](https://github.com/mollie/mollie-api-node/pull/292)/[#293](https://github.com/mollie/mollie-api-node/pull/293)) From 1c09488fe3dec7a1345fca51638b77dc9940576c Mon Sep 17 00:00:00 2001 From: "Pimm \"de Chinchilla\" Hogeling" Date: Tue, 17 Sep 2024 01:24:09 +0200 Subject: [PATCH 2/6] Add migration guide for v4.0.0. --- MIGRATION.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 110 insertions(+), 2 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 71704fc1..3a375bd3 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -1,4 +1,112 @@ -# 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. 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) + } +``` + +## 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 +``` + +## List API changes + +The return type of list functions now reflects whether the underlying endpoint is paginated. The following functions now return (plain) arrays: + + * `mollieClient.methods.list` + * `mollieClient.orderShipments.list` + * `mollieClient.permissions.list` + +The following functions now 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. + +# Migrating from v2.×.× to v3.0.0 ## Initialization @@ -60,7 +168,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. From e2ee4bb5ff4a4177987fc5bfd8225179454b6783 Mon Sep 17 00:00:00 2001 From: "Pimm \"de Chinchilla\" Hogeling" Date: Tue, 17 Sep 2024 00:19:34 +0200 Subject: [PATCH 3/6] Update link in readme. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 8d762e94..a48ac278 100644 --- a/README.md +++ b/README.md @@ -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 From c81b6f7be6197bf4a0caa0bd5b81366d3dbe8227 Mon Sep 17 00:00:00 2001 From: "Pimm \"de Chinchilla\" Hogeling" Date: Tue, 17 Sep 2024 01:32:56 +0200 Subject: [PATCH 4/6] Add clarification to migration guide. --- MIGRATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION.md b/MIGRATION.md index 3a375bd3..1fdbf29e 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -45,7 +45,7 @@ Helper functions which do not provide a significantly simpler API have been remo ## Removed functions from `ApiError` -`getMessage`, `getField`, `getStatusCode` have been removed. Please use `message`, `field`, and `statusCode` instead: +`getMessage`, `getField`, `getStatusCode` have been removed from `ApiError`. Please use `message`, `field`, and `statusCode` instead: ```diff try { const payment = await mollieClient.payments.get(…); From fd35bfc3733809362647dc36d49b84a3ffc602a0 Mon Sep 17 00:00:00 2001 From: "Pimm \"de Chinchilla\" Hogeling" Date: Tue, 17 Sep 2024 01:36:09 +0200 Subject: [PATCH 5/6] Extend the migration guide. --- MIGRATION.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 1fdbf29e..e4d8c6d9 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -69,15 +69,15 @@ The `count` property has been removed from pages, please use `length` instead: + mollieClient.payments.page({ limit: 10 }).length ``` -## List API changes +## Changed return type of list functions -The return type of list functions now reflects whether the underlying endpoint is paginated. The following functions now return (plain) arrays: +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 now return iterators: +The following functions return iterators: * `customer.getMandates()` * `customer.getSubscriptions()` @@ -106,6 +106,10 @@ Previously, it was possible to provide options to Axios through `createMollieCli Please [create an issue](https://github.com/mollie/mollie-api-node/issues/new) if you rely on such an option. +## Note: network errors may have changed + +It is possible that network issues produce different error messages compared to previous versions of the client. Please update your error handling code if necessary. + # Migrating from v2.×.× to v3.0.0 ## Initialization From 1010dc8dc9439887fc5bef1b7922c0b97d30faa9 Mon Sep 17 00:00:00 2001 From: "Pimm \"de Chinchilla\" Hogeling" Date: Tue, 17 Sep 2024 08:55:03 +0200 Subject: [PATCH 6/6] Tweaked changelog and migration guide. --- CHANGELOG.md | 2 +- MIGRATION.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c8220e0a..5df75587 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,7 @@ ### 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-16 - 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)) diff --git a/MIGRATION.md b/MIGRATION.md index e4d8c6d9..020904ae 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -106,9 +106,9 @@ Previously, it was possible to provide options to Axios through `createMollieCli Please [create an issue](https://github.com/mollie/mollie-api-node/issues/new) if you rely on such an option. -## Note: network errors may have changed +## Note: network error messages may have changed -It is possible that network issues produce different error messages compared to previous versions of the client. Please update your error handling code if necessary. +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