stripe 21.1.0-beta.2 → 22.0.1

package/README.md

@@ -41,27 +41,30 @@ value:
 
 <!-- prettier-ignore -->
 ```js
-const stripe = require('stripe')('sk_test_...');
+import Stripe from 'stripe';
+const stripeClient = new Stripe('sk_test_...');
+
+const customer = await stripeClient.customers.create({
+  email: 'customer@example.com',
+});
+
+console.log(customer.id);
+```
+
+Or using CJS:
+```js
+const Stripe = require('stripe');
+const stripeClient = Stripe('sk_test_...');
 
-stripe.customers.create({
+stripeClient.customers.create({
   email: 'customer@example.com',
 })
   .then(customer => console.log(customer.id))
   .catch(error => console.error(error));
 ```
 
-Or using ES modules and `async`/`await`:
-
-```js
-import Stripe from 'stripe';
-const stripe = new Stripe('sk_test_...');
 
-const customer = await stripe.customers.create({
-  email: 'customer@example.com',
-});
 
-console.log(customer.id);
-```
 
 > [!WARNING]
 > If you're using `v17.x.x` or later and getting an error about a missing API key despite being sure it's available, it's likely you're importing the file that instantiates `Stripe` while the key isn't present (for instance, during a build step).
@@ -71,7 +74,7 @@ console.log(customer.id);
 > import Stripe from 'stripe';
 >
 > let _stripe: Stripe | null = null;
-> const getStripe = (): Stripe => {
+> const getStripeClient = (): Stripe => {
 >   if (!_stripe) {
 >     _stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string, {
 >       // ...
@@ -80,7 +83,7 @@ console.log(customer.id);
 >   return _stripe;
 > };
 >
-> const getCustomers = () => getStripe().customers.list();
+> const getCustomers = () => getStripeClient().customers.list();
 > ```
 >
 > Alternatively, you can provide a placeholder for the real key (which will be enough to get the code through a build step):
@@ -88,7 +91,7 @@ console.log(customer.id);
 > ```ts
 > import Stripe from 'stripe';
 >
-> export const stripe = new Stripe(
+> export const stripeClient = new Stripe(
 >   process.env.STRIPE_SECRET_KEY || 'api_key_placeholder',
 >   {
 >     // ...
@@ -105,14 +108,14 @@ and instantiate it as `new Stripe()` with the latest API version.
 
 ```ts
 import Stripe from 'stripe';
-const stripe = new Stripe('sk_test_...');
+const stripeClient = new Stripe('sk_test_...');
 
 const createCustomer = async () => {
   const params: Stripe.CustomerCreateParams = {
     description: 'test customer',
   };
 
-  const customer: Stripe.Customer = await stripe.customers.create(params);
+  const customer: Stripe.Customer = await stripeClient.customers.create(params);
 
   console.log(customer.id);
 };
@@ -142,7 +145,7 @@ We also recommend using `// @ts-ignore` if you have access to a beta feature and
 so you must cast them appropriately, e.g.,
 
 ```ts
-const paymentIntent: Stripe.PaymentIntent = await stripe.paymentIntents.retrieve(
+const paymentIntent: Stripe.PaymentIntent = await stripeClient.paymentIntents.retrieve(
   'pi_123456789',
   {
     expand: ['customer'],
@@ -171,7 +174,7 @@ callback:
 
 ```js
 // Create a new customer and then create an invoice item then invoice it:
-stripe.customers
+stripeClient.customers
   .create({
     email: 'customer@example.com',
   })
@@ -249,7 +252,7 @@ const stripe = Stripe('sk_test_...', {
 Timeout can be set globally via the config object:
 
 ```js
-const stripe = Stripe('sk_test_...', {
+const stripeClient = Stripe('sk_test_...', {
   timeout: 20 * 1000, // 20 seconds
 });
 ```
@@ -257,7 +260,7 @@ const stripe = Stripe('sk_test_...', {
 And overridden on a per-request basis:
 
 ```js
-stripe.customers.create(
+stripeClient.customers.create(
   {
     email: 'customer@example.com',
   },
@@ -274,7 +277,7 @@ can be added to any method:
 
 ```js
 // List the balance transactions for a connected account:
-stripe.balanceTransactions.list(
+stripeClient.balanceTransactions.list(
   {
     limit: 10,
   },
@@ -303,13 +306,13 @@ if (process.env.http_proxy) {
 As of [v13](https://github.com/stripe/stripe-node/releases/tag/v13.0.0) stripe-node will automatically do one reattempt for failed requests that are safe to retry. Automatic network retries can be disabled by setting the `maxNetworkRetries` config option to `0`. You can also set a higher number to reattempt multiple times, with exponential backoff. [Idempotency keys](https://stripe.com/docs/api/idempotent_requests) are added where appropriate to prevent duplication.
 
 ```js
-const stripe = Stripe('sk_test_...', {
+const stripeClient = Stripe('sk_test_...', {
   maxNetworkRetries: 0, // Disable retries
 });
 ```
 
 ```js
-const stripe = Stripe('sk_test_...', {
+const stripeClient = Stripe('sk_test_...', {
   maxNetworkRetries: 2, // Retry a request twice before giving up
 });
 ```
@@ -317,7 +320,7 @@ const stripe = Stripe('sk_test_...', {
 Network retries can also be set on a per-request basis:
 
 ```js
-stripe.customers.create(
+stripeClient.customers.create(
   {
     email: 'customer@example.com',
   },
@@ -342,17 +345,18 @@ customer.lastResponse.statusCode;
 The Stripe object emits `request` and `response` events. You can use them like this:
 
 ```js
-const stripe = require('stripe')('sk_test_...');
+const Stripe = require('stripe');
+const stripeClient = Stripe('sk_test_...');
 
 const onRequest = (request) => {
   // Do something.
 };
 
 // Add the event handler function:
-stripe.on('request', onRequest);
+stripeClient.on('request', onRequest);
 
 // Remove the event handler function:
-stripe.off('request', onRequest);
+stripeClient.off('request', onRequest);
 ```
 
 #### `request` object
@@ -394,7 +398,7 @@ Please note that you must pass the _raw_ request body, exactly as received from
 You can find an example of how to use this with various JavaScript frameworks in [`examples/webhook-signing`](examples/webhook-signing) folder, but here's what it looks like:
 
 ```js
-const event = stripe.webhooks.constructEvent(
+const event = stripeClient.webhooks.constructEvent(
   webhookRawBody,
   webhookStripeSignatureHeader,
   webhookSecret
@@ -403,7 +407,7 @@ const event = stripe.webhooks.constructEvent(
 
 #### Testing Webhook signing
 
-You can use `stripe.webhooks.generateTestHeaderString` to mock webhook events that come from Stripe:
+You can use `stripeClient.webhooks.generateTestHeaderString` to mock webhook events that come from Stripe:
 
 ```js
 const payload = {
@@ -414,12 +418,12 @@ const payload = {
 const payloadString = JSON.stringify(payload, null, 2);
 const secret = 'whsec_test_secret';
 
-const header = stripe.webhooks.generateTestHeaderString({
+const header = stripeClient.webhooks.generateTestHeaderString({
   payload: payloadString,
   secret,
 });
 
-const event = stripe.webhooks.constructEvent(payloadString, header, secret);
+const event = stripeClient.webhooks.constructEvent(payloadString, header, secret);
 
 // Do something with mocked signed event
 expect(event.id).to.equal(payload.id);
@@ -435,8 +439,10 @@ See [undocumented params and properties](https://docs.stripe.com/sdks/server-sid
 
 If you're writing a plugin that uses the library, we'd appreciate it if you instantiated your stripe client with `appInfo`, eg;
 
+With ES modules or TypeScript:
 ```js
-const stripe = require('stripe')('sk_test_...', {
+import Stripe from "stripe";
+const stripeClient = new Stripe(apiKey, {
   appInfo: {
     name: 'MyAwesomePlugin',
     version: '1.2.34', // Optional
@@ -445,10 +451,10 @@ const stripe = require('stripe')('sk_test_...', {
 });
 ```
 
-Or using ES modules or TypeScript:
-
+Or using CJS:
 ```js
-const stripe = new Stripe(apiKey, {
+const Stripe = require('stripe');
+const stripeClient = Stripe('sk_test_...', {
   appInfo: {
     name: 'MyAwesomePlugin',
     version: '1.2.34', // Optional
@@ -457,6 +463,7 @@ const stripe = new Stripe(apiKey, {
 });
 ```
 
+
 This information is passed along when the library makes calls to the Stripe API.
 
 ### Auto-pagination
@@ -470,7 +477,7 @@ such as Node 10+ or [babel](https://babeljs.io/docs/en/babel-plugin-transform-as
 the following will auto-paginate:
 
 ```js
-for await (const customer of stripe.customers.list()) {
+for await (const customer of stripeClient.customers.list()) {
   doSomething(customer);
   if (shouldStop()) {
     break;
@@ -484,7 +491,7 @@ If you are in a Node environment that has support for `await`, such as Node 7.9
 you may pass an async function to `.autoPagingEach`:
 
 ```js
-await stripe.customers.list().autoPagingEach(async (customer) => {
+await stripeClient.customers.list().autoPagingEach(async (customer) => {
   await doSomething(customer);
   if (shouldBreak()) {
     return false;
@@ -496,7 +503,7 @@ console.log('Done iterating.');
 Equivalently, without `await`, you may return a Promise, which can resolve to `false` to break:
 
 ```js
-stripe.customers
+stripeClient.customers
   .list()
   .autoPagingEach((customer) => {
     return doSomething(customer).then(() => {
@@ -521,7 +528,7 @@ to prevent runaway list growth from consuming too much memory. Once the
 Returns a promise of an array of all items across pages for a list request.
 
 ```js
-const allNewCustomers = await stripe.customers
+const allNewCustomers = await stripeClient.customers
   .list({created: {gt: lastMonth}, limit: 100}) // 100 items per page
   .autoPagingToArray({limit: 10000}); // Stop after 10000 items total
 ```
@@ -536,7 +543,7 @@ improve popular features.
 You can disable this behavior if you prefer:
 
 ```js
-const stripe = new Stripe('sk_test_...', {
+const stripeClient = new Stripe('sk_test_...', {
   telemetry: false,
 });
 ```
@@ -566,7 +573,7 @@ npm install stripe@<some-version>
 Some preview features require a name and version to be set in the `Stripe-Version` header like `feature_beta=v3`. If your preview feature has this requirement, use the `apiVersion` property of `config` object to set it:
 
 ```js
-const stripe = new Stripe('sk_test_...', {
+const stripeClient = new Stripe('sk_test_...', {
   apiVersion: '2022-08-01; feature_beta=v3',
 });
 ```
@@ -585,21 +592,7 @@ npm install stripe@private-preview --save-exact
 
 If you would like to send a request to an undocumented API (for example you are in a private beta), or if you prefer to bypass the method definitions in the library and specify your request details directly, you can use the `rawRequest` method on the StripeClient object.
 
-```javascript
-import Stripe from 'stripe';
-const client = new Stripe('sk_test_...');
-
-client.rawRequest(
-    'POST',
-    '/v1/beta_endpoint',
-    { param: 123 },
-    { apiVersion: '2022-11-15; feature_beta=v3' }
-  )
-  .then((response) => /* handle response */ )
-  .catch((error) => console.error(error));
-```
-
-Or using ES modules and `async`/`await`:
+Using ES modules and `async`/`await`:
 
 ```javascript
 import Stripe from 'stripe';
@@ -615,6 +608,21 @@ const response = await stripe.rawRequest(
 // handle response
 ```
 
+Or using CJS and promises:
+
+```javascript
+const stripeClient = new Stripe('sk_test_...');
+
+stripeClient.rawRequest(
+    'POST',
+    '/v1/beta_endpoint',
+    { param: 123 },
+    { apiVersion: '2022-11-15; feature_beta=v3' }
+  )
+  .then((response) => /* handle response */ )
+  .catch((error) => console.error(error));
+```
+
 ## Support
 
 New features and bug fixes are released on the latest major version of the `stripe` package. If you are on an older major version, we recommend that you upgrade to the latest in order to use the new features and bug fixes including those for security vulnerabilities. Older major versions of the package will continue to be available for use, but will not be receiving any updates.

package/VERSION

@@ -1 +1 @@
-21.1.0-beta.2
+22.0.1