Deprecate many library api's, unify others

[rattrayalex-stripe]

r? @richardm-stripe
cc @ob-stripe @jlomas-stripe @paulasjes-stripe

Much of the tricky stuff here is wrestling with questions of what should be private, what should be private-but-you-can-poke-it-anyway, etc. It might be healthier for my sanity to kick these cans down the road a bit more, but probably healthier for the library to deal with them sooner rather than later, especially if we want to upgrade our internals to TS etc in the medium term.

---

Breaking changes

[BREAKING] Remove deprecated Error base export, extend method, and populate method

You can no longer do this:

const MyStripeError = StripeError.extend({});

Instead, you can do this:

class MyStripeError extends StripeError {}

You can no longer do this (which should not have had a legitimate use-case):

const StripeGenericError = require('stripe/lib/Error');

Instead, use the named export StripeError:

const {StripeError} = require('stripe/lib/Error');
// or
const Stripe = require('stripe');
const {StripeError} = Stripe.errors;

[BREAKING] Privatize several constants

The following constants are no longer accessible:

Stripe.DEFAULT_HOST
Stripe.DEFAULT_PORT
Stripe.DEFAULT_BASE_PATH
Stripe.DEFAULT_API_VERSION
Stripe.DEFAULT_TIMEOUT
Stripe.MAX_NETWORK_RETRY_DELAY_SEC
Stripe.INITIAL_NETWORK_RETRY_DELAY_SEC

Instead, you can read them like so:

Stripe.getConstant('DEFAULT_HOST');

Though we may remove this in the future, so please file an issue with your use case if you rely on this functionality.

To set a value you like this, use a config option when instantiating the Stripe client, e.g.,

const stripe = new Stripe(apiKey, {
  host,
  port,
  basePath,
  timeout,
  apiVersion,
});

Non-breaking changes

Deprecate snake_case options like stripe_account with warning messages

Doing, e.g., stripe.customers.create(params, {api_key: foo}) will now emit a warning message encouraging you to use apiKey instead.

Add protocol to config object for local proxies etc

You can now instantiate a stripe client with a non-https protocol, e.g.,

const stripe = new Stripe(apiKey, {
  host: '127.0.0.1',
  port: 3000,
  protocol: 'http',
});

This is intended for tests and proxies. All production traffic must be https only.

This replaces stripe.setProtocol() and stripe.setHost(host, port, protocol), which are deprecated.

Add appInfo to config object

Stripe plugin authors can now instantiate a stripe client with appInfo instead of using stripe.setAppInfo, eg;

const stripe = new Stripe(apiKey, {
  appInfo: {
    name: 'MyCoolPlugin',
  }
});

Mark all setter methods as deprecated, emit warnings.

Setter methods like stripe.setApiVersion() were previously deprecated; now, they emit deprecation warnings. Please move to the config object or request options instead.

For example, instead of this:

const stripe = new Stripe(apiKey);
stripe.setApiVersion('2019-11-03');

You could do this:

const stripe = new Stripe(apiKey, {apiVersion: '2019-11-03'});
stripe.customers.list();

Or this:

const stripe = new Stripe(apiKey);
stripe.customers.list({apiVersion: '2019-11-03'});

Mark methods prefixed with an underscore as private

Methods like _setAppInfo which are intended for private use now have a docstring indicating they are private, and may be removed in the future.

If you rely on any underscore-prefixed methods, please open an issue on github detailing your use-case.

Mark a few getter methods which are not prefixed with underscores as private

The following getter methods were likely always intended for private use only, but may be used for reasons we haven’t yet thought of. We may remove them in the future.

stripe.getApiField()
stripe.getConstant()
stripe.getClientUserAgent()
stripe.getClientUserAgentSeeded()
stripe.getAppInfoAsString()

If you are relying on any of these, please let us know.

Rename the request option stripeVersion to apiVersion

We previously used stripeVersion and did not have apiVersion here, which was inconsistent with how you instantiate the stripe client: new Stripe(apiKey, {apiVersion: '2019-12-03'}).

Instead of this:

stripe.customers.list({stripeVersion: '2019-11-03'});

Please do this instead:

stripe.customers.list({apiVersion: '2019-11-03'});

The former will now log a warning message, but will continue to work as expected.

[rattrayalex-stripe]

These constants I'm moderately worried about removing. Users could previously read/write them, though I don't think that was ever intended.

They can still read them with Stripe.getConstant and all of them have proper ways of writing, eg new Stripe(key, {host, port, basePath, apiVersion, timeout})

[rattrayalex-stripe]

cc @ob-stripe @remi-stripe

[rattrayalex-stripe]

r? @richardm-stripe change enacted in e756c7f