Migration guide for v8

(See also: Migration guide for v7).

PR: https://github.com/stripe/stripe-node/pull/742

Summary

In stripe-node version 8.0.0, we are releasing first-class TypeScript support, ending support for Node 6 (thus requiring Node 8, 10, or higher), and removing a few deprecated API resources and library methods (mostly internal constants and obscure uses of Errors).

Note that stripe.usageRecords.create() is now stripe.subscriptionItems.createUsageRecord(), and stripe.usageRecordSummaries.list() is now stripe.subscriptionItems.listUsageRecordSummaries().

Options in snake_case have been changed to camelCase, and the stripeVersion request option is now apiVersion. Console warnings will be emitted if you use the old versions.

Many methods intended for private use are now marked as such; please let us know if you need to use them, as we may remove them in the next major version.

Breaking Changes

Rename usage record resources

PR: https://github.com/stripe/stripe-node/pull/744

• stripe.usageRecords.create() is now stripe.subscriptionItems.createUsageRecord()
• stripe.usageRecordSummaries.list() is now stripe.subscriptionItems.listUsageRecordSummaries()

Removed deprecated API resources

PR: https://github.com/stripe/stripe-node/pull/744

• stripe.recipients is removed
• stripe.bitcoinReceivers is removed
• stripe.threeDSecure is removed

Removed deprecated Error base export, extend method, and populate method

PR: https://github.com/stripe/stripe-node/pull/752

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 Error = 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;

or the builtin Error.

Privatized several constants

PR: https://github.com/stripe/stripe-node/pull/752

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

PR: https://github.com/stripe/stripe-node/pull/752

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

PR: https://github.com/stripe/stripe-node/pull/752

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

PR: https://github.com/stripe/stripe-node/pull/752

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.

PR: https://github.com/stripe/stripe-node/pull/752

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

PR: https://github.com/stripe/stripe-node/pull/752

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

PR: https://github.com/stripe/stripe-node/pull/752

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

PR: https://github.com/stripe/stripe-node/pull/752

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.