New config object base and apiVersion

[paulasjes-stripe]

Part 1 of #703

This adds the ability to pass in a configuration object as the 2nd parameter of Stripe. For example:

const stripe = new Stripe('sk_test_123', {
  apiVersion: '2019-09-09',
)};

This allows the old behavior to still work:

const stripe = new Stripe('sk_test_123', '2019-09-09');

Additionally this behavior will also still work:

const stripe = new Stripe('sk_test_123');
stripe.setApiVersion('2019-09-09');

With the idea being of eventually deprecating stripe.setApiVersion in favor of the config object.

r? @rattrayalex-stripe @ob-stripe @richardm-stripe
cc @stripe/api-libraries

[rattrayalex-stripe]

Nice, glad to see this picking up steam again! Like the restrictive approach & tests.
ptal @paulasjes-stripe

[rattrayalex-stripe]

In rare cases we've required api versions of the form YYYY-MM-DD foo_beta=v1, and we'd probably like to preserve the ability to do that

[paulasjes-stripe]

TIL! Is it conceivable that api versions could take the form of foo=bar YYYY-MM-DD or would we only expect additional parameters after the date string?

[paulasjes-stripe]

Also is something like this possible: YYYY-MM-DD foo_beta=v1 bar_beta=v2?

I'm thinking that maybe the regex just checks for the date at the beginning of the string and doesn't care about what comes after.

[rattrayalex-stripe]

I think I'd rather forego regex checks unless they're really necessary, and rely on the api to tell the user that the string doesn't fit. Just buys us the most flexibility. Thoughts?

[paulasjes-stripe]

I like the concept of failing as soon as possible if something is obviously wrong. If I were to initialize stripe-node like so:

const stripe = new Stripe('sk_test_123', 'bananas');

Then stripe-node would happily return a version of Stripe with a bogus api version. The error won't occur until we actually attempt to make a request.

I think that this sort of clearly wrong input should be caught and handled before any request is made.

Saying that, if we have too many API version format options and edge cases, then I'm happy to let the API take care of that for us.

[rattrayalex-stripe]

Ah sorry, missed this comment earlier – earlier error messages are certainly better than later ones, but the error message from the API about an invalid version string should come pretty quick, no?

Furthermore the client can't have enough information to make an accurate decision – we can't disallow a valid date which isn't a valid api version, and may indeed allow "bananas" at one point in the future for a very special beta program!

[rattrayalex-stripe]

nit, I think it might make sense to early-return {apiVersion: config} here, since it'll be impossible to set other properties later anyway.

Then, later on, we can just return config

[paulasjes-stripe]

Addressed your feedback and added more tests for edge cases, ptal @rattrayalex-stripe @richardm-stripe

[rattrayalex-stripe]

Ah, I do feel quite bad for being rather unclear earlier; I think we should probably accept any string for the version (unless there's a danger of a user passing a bad string with another intent or something).

EDIT: Just to provide some color here, I have a distinct memory of a member of our api platform team being quite grateful that we didn't do any API Version regex verification in our client libraries, since it gave us freedom to choose any format we like. I could imagine in the future, for example, wanting to allow "default" as an explicit override in certain situations (instead of "latest", or some other similar magic string).

ptal @paulasjes-stripe

[paulasjes-stripe]

@rattrayalex-stripe You've convinced me that the regex is a bad idea, so I removed it. Have a look now

[richardm-stripe]

lgtm

[rattrayalex-stripe]

🎉