search

mollie / mollie-api-node

Official Mollie API client for Node
http://www.mollie.com
BSD 3-Clause "New" or "Revised" License
237 stars 63 forks source link

Undocumented and slightly odd interface for mandates #102

Closed 0x80 closed 5 years ago

0x80 commented 5 years ago

I could not find anything about fetching mandates so I went into the source and figure this out:

const mandate = await mollieClient.customers_mandates.get(
          payment.mandateId,
          { customerId: user.data.mollieCustomerId }
        );

It would help a lot if this kind of thing was documented somewhere. Also the customer_mandates function name seems odd for a Javascript method name.

Of course #70 would also help a lot with this kind of thing.

DigitalLeaves commented 5 years ago

Hello @0x80, I agree with you, Mollie needs to put together a documentation for Node.js. As for mandates, I use this one for retrieving the mandates of a user, and works quite well asynchronously (as long as your don't nest it with any other mollie call):

mollie.customers_mandates.all({customerId: customerId}, function (err, mandates) {
            if (err || !mandates) {
                var msg = "Error retrieving mandates for customer "+customerId+". "
                if (err && err.message) { msg += err.message } else { msg += "Customer or mandates not found."}
                return callback(new Error(msg))
            } else {
                return callback(null, mandates)
            }
        })

Hope it helps!

vernondegoede commented 5 years ago

@0x80 We have quite some examples in the examples directory of this module. It also includes an example which retrieves a single mandate.

Regarding documentation improvements, we're currently working on:

  1. Switching to TypeScript. This should help a lot when using the Node API client. (#70)
  2. Adding the code examples to the API documentation on docs.mollie.com. This is currently blocked by the TypeScript migration though. (https://github.com/mollie/api-documentation/pull/378)

I'm closing this issue for now – please let us know if you have any ideas on how to further improve our documentation / examples. Any feedback on how we can improve our products is always appreciated. 👍

vernondegoede commented 5 years ago

We've just released a beta version of the Node API client 3.0.0, which comes with the following changes:

Check out the changelog Check out the migration guide

Feel free to test the beta and let us know if you have any feedback!

$ yarn add @mollie/api-client@beta
DigitalLeaves commented 5 years ago

Thanks for the info, I will have a look into this. And congrats. Exciting news to have a new version of the API. Hopefully it will address some of the stuff Mollie could improve upon, and also offer a better documentation for Node.js!

Some initial feedback without delving into the new API:

  1. In the migration guide, it would be SUPER nice to add when the migration will occur. Meaning, I have a npm update automatically included in my git webhook after a push to the backend's remote site. If I add a change right now and the npm package of Mollie updates... will that break my production server because of the function definition changes? I.E:
- const mollieClient = require('@mollie/api-client')({
+ const mollieClient = require('@mollie/api-client').createMollieClient({
    apiKey: 'test_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM',
  })
  1. Can you please change the link at the changelog to the migration site? (https://github.com/mollie/mollie-api-node/blob/master/docs/migration_v3_x.md) it's not working.
Pimm commented 5 years ago

Hi @DigitalLeaves!

As for the when: the breaking changes are in 2.3.2 → 3.0.0.

npm uses semver. You likely have your Mollie dependency defined in your package.json similar to this: "@mollie/api-client": "^2.2.0" If so, it will not update to 3.0.0. Instead, it will update to the latest 2.× version (which is 2.3.2).

The new version is currently in beta. If you wish to start using it today, change the dependency in your package.json to: "@mollie/api-client": "^3.0.0-beta" That would require you to migrate.

Alternatively, you can wait for for the new version to receive an official release. At that point in time, you may change the dependency in your package.json to: "@mollie/api-client": "^3.0.0"

tl;dr

As long as the dependency in your package.json is defined as "^2.2.0" or similar, you will not have to migrate and your server will not break.

DigitalLeaves commented 5 years ago

Thanks! I really appreciated that. By the way, no need for a TL;DR, I'm not a millennial, so it's ok for me to read more than 2-3 paragraphs of text 😂.

Jokes aside, I'll have a look at the API and will be happy to offer some feedback if you ask for it, of course.

Thanks!