Merge to private-preview

CHANGELOG.md

@@ -88,6 +88,12 @@ This release changes the pinned API version to 2026-05-27.private.
   * Add support for snapshot event `PaymentIntentExpiredEvent` with resource `PaymentIntent`
   * Add support for event notifications `V2CoreHealthElementsErrorFiringEvent`, `V2CoreHealthElementsErrorResolvedEvent`, `V2CoreHealthInvoiceCountDroppedFiringEvent`, and `V2CoreHealthInvoiceCountDroppedResolvedEvent`
 
+## 22.2.1 - 2026-06-12
+* [#2750](https://github.com/stripe/stripe-node/pull/2750) URI Encode path params
+* [#2747](https://github.com/stripe/stripe-node/pull/2747) Fix V2ListIterator: concurrency guard and empty page handling
+* [#2740](https://github.com/stripe/stripe-node/pull/2740) Add "source" field to user-agent header
+* [#2734](https://github.com/stripe/stripe-node/pull/2734) Fix parseHttpHeaderAsNumber to return undefined instead of NaN
+
 ## 22.2.0 - 2026-05-27
 This release changes the pinned API version to 2026-05-27.dahlia.
 
@@ -146,12 +152,12 @@ This release changes the pinned API version to 2026-05-27.dahlia.
   * Adds `V2List` and `V2ListPromise` types to represent API v2 list responses.  These types include deprecated fields from the previously returned list shapes.  These fields will be removed in the next major release.
 * [#2715](https://github.com/stripe/stripe-node/pull/2715) Add WinterTC compatibility ESLint rule
 * [#2711](https://github.com/stripe/stripe-node/pull/2711) Export manually maintained types for OAuthToken and OAuth param classes
-  ```ts
-  // ❌ Before (v22.0.0-v22.1.1)
-  const oAuthToken: Stripe.OAuthToken = {};
-  
-  // ✅ After (works on v22.1.2+)
-  const oAuthToken: Stripe.OAuthToken = {};
+  ```ts
+  // ❌ Before (v22.0.0-v22.1.1)
+  const oAuthToken: Stripe.OAuthToken = {};
+
+  // ✅ After (works on v22.1.2+)
+  const oAuthToken: Stripe.OAuthToken = {};
   ```
 * [#2712](https://github.com/stripe/stripe-node/pull/2712) Exported types for nested param classes
   * Types inside nested param class namespaces(e.g. `Stripe.V2.Core.AccountCreateParams.Configuration`, `Stripe.V2.Core.AccountCreateParams.Dashboard`) are now accessible.
@@ -438,10 +444,10 @@ This release changes the pinned API version to 2026-04-22.private.
 
 ## 22.1.1 - 2026-05-06
 * [#2703](https://github.com/stripe/stripe-node/pull/2703) Export Decimal type from Stripe namespace
-  
+
   - Added `Stripe.Decimal` as a usable type in the `Stripe` namespace, enabling type annotations like `function takesDecimal(d: Stripe.Decimal)`.
 * [#2704](https://github.com/stripe/stripe-node/pull/2704) Fix file upload regression: restore multipart request data processor
-  
+
   - Fixed file uploads failing with `StripeInvalidRequestError` on the `/v1/files` endpoint since v22.
 
 ## 22.1.0 - 2026-04-23
@@ -597,32 +603,32 @@ This release changes the pinned API version to 2026-04-01.preview and contains a
 ## 22.0.2 - 2026-04-16
 * [#2685](https://github.com/stripe/stripe-node/pull/2685) Adds `parseEventNotificationAsync` to match existing sync function
 * [#2681](https://github.com/stripe/stripe-node/pull/2681) Add emitEventBodies config to include bodies in request/response events
-  - Added `emitEventBodies` config option to include request and response bodies in `request`/`response` events.
+  - Added `emitEventBodies` config option to include request and response bodies in `request`/`response` events.
   - Changed `httpClient` config type from `HttpClient` class to `HttpClientInterface` interface.
 * [#2670](https://github.com/stripe/stripe-node/pull/2670) tolerance, receivedAt, timestamp are now optional in Webhook.ts
 * [#2677](https://github.com/stripe/stripe-node/pull/2677) Fixed named export for Bun
-  ```ts
-  // ✅ Fixed
-  import { Stripe } from 'stripe';
+  ```ts
+  // ✅ Fixed
+  import { Stripe } from 'stripe';
   ```
 
 ## 22.0.1 - 2026-04-08
 * [#2669](https://github.com/stripe/stripe-node/pull/2669) Add constructor based initialization for CJS based TypeScript imports
-  * Initialization of Stripe class with `new` keyword is now possible for CJS based TypeScript project. Resolves: [2660](https://github.com/stripe/stripe-node/issues/2660)
-  ```ts
-  import Stripe = require('stripe');
-  // ✅ Both statements work
-  const stripeNew: Stripe.Stripe = new Stripe('sk_test_...');
-  const stripeCalled: Stripe.Stripe = Stripe('sk_test_...');
+  * Initialization of Stripe class with `new` keyword is now possible for CJS based TypeScript project. Resolves: [2660](https://github.com/stripe/stripe-node/issues/2660)
+  ```ts
+  import Stripe = require('stripe');
+  // ✅ Both statements work
+  const stripeNew: Stripe.Stripe = new Stripe('sk_test_...');
+  const stripeCalled: Stripe.Stripe = Stripe('sk_test_...');
   ```
 * [#2664](https://github.com/stripe/stripe-node/pull/2664) Fixed nested service param exports in the Stripe namespace
   * Resolves: [2658](https://github.com/stripe/stripe-node/issues/2658),  [2662](https://github.com/stripe/stripe-node/issues/2662)
 * [#2667](https://github.com/stripe/stripe-node/pull/2667) Add type safety to Stripe constructor config (no runtime change)
-  - Fixed some compile-time checks (no runtime changes)
-    - Fixed `Stripe` constructor config parameter to use `StripeConfig` type instead of `Record<string, unknown>`, restoring compile-time type safety.
-    - Added missing `authenticator` property to `StripeConfig`.
-    - Fixed `Stripe.API_VERSION` to retain the literal API version type.
-    - Fixed `StripeConfig.stripeContext` to accept `StripeContext` objects in addition to strings.
+  - Fixed some compile-time checks (no runtime changes)
+    - Fixed `Stripe` constructor config parameter to use `StripeConfig` type instead of `Record<string, unknown>`, restoring compile-time type safety.
+    - Added missing `authenticator` property to `StripeConfig`.
+    - Fixed `Stripe.API_VERSION` to retain the literal API version type.
+    - Fixed `StripeConfig.stripeContext` to accept `StripeContext` objects in addition to strings.
 * [#2663](https://github.com/stripe/stripe-node/pull/2663) Throw a more descriptive error when calling `rawRequest` with absolute urls
 * [#2652](https://github.com/stripe/stripe-node/pull/2652) Added `string[]` to `WebhookHeader` type for compatibility with express
   * Added `string[]` to the type of `signature` param in `stripe.webhooks.construct_event` method.

README.md

@@ -42,24 +42,25 @@ value:
 ```js
 const stripe = require('stripe')('sk_test_...');
 
-stripe.customers.create({
+const customer = await stripeClient.customers.create({
   email: 'customer@example.com',
-})
-  .then(customer => console.log(customer.id))
-  .catch(error => console.error(error));
+});
+
+console.log(customer.id);
 ```
 
-Or using ES modules and `async`/`await`:
+Or using CJS:
 
 ```js
-import Stripe from 'stripe';
-const stripe = new Stripe('sk_test_...');
+const Stripe = require('stripe');
+const stripeClient = Stripe('sk_test_...');
 
-const customer = await stripe.customers.create({
-  email: 'customer@example.com',
-});
-
-console.log(customer.id);
+stripeClient.customers
+  .create({
+    email: 'customer@example.com',
+  })
+  .then((customer) => console.log(customer.id))
+  .catch((error) => console.error(error));
 ```
 
 > [!WARNING]
@@ -420,7 +421,11 @@ const header = stripe.webhooks.generateTestHeaderString({
   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);
@@ -436,27 +441,18 @@ 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;
 
-```js
-const stripe = require('stripe')('sk_test_...', {
-  appInfo: {
-    name: 'MyAwesomePlugin',
-    version: '1.2.34', // Optional
-    url: 'https://myawesomeplugin.info', // Optional
-  },
-});
-```
+With ES modules or TypeScript:
 
-Or using ES modules or TypeScript:
-
-```js
-const stripe = new Stripe(apiKey, {
+````js
+import Stripe from 'stripe';
+const stripeClient = new Stripe(apiKey, {
   appInfo: {
     name: 'MyAwesomePlugin',
     version: '1.2.34', // Optional
     url: 'https://myawesomeplugin.info', // Optional
   },
 });
-```
+``
 
 This information is passed along when the library makes calls to the Stripe API.
 
@@ -477,7 +473,7 @@ for await (const customer of stripe.customers.list()) {
     break;
   }
 }
-```
+````
 
 #### `autoPagingEach`
 
@@ -629,6 +625,9 @@ New features and bug fixes are released on the latest major version of the `stri
 
 ## Development
 
+> [!WARNING]
+> External contributions to this repo from first-time contributors are currently on hiatus. If you'd like to see a change made to the package, please open an issue.(
+
 [Contribution guidelines for this project](CONTRIBUTING.md)
 
 The tests depend on [stripe-mock][stripe-mock], so make sure to fetch and

src/resources/AccountNotices.ts

@@ -26,7 +26,7 @@ export class AccountNoticeResource extends StripeResource {
   ): Promise<Response<AccountNotice>> {
     return this._makeRequest(
       'GET',
-      `/v1/account_notices/${id}`,
+      `/v1/account_notices/${encodeURIComponent(id)}`,
       params,
       options
     ) as any;
@@ -41,7 +41,7 @@ export class AccountNoticeResource extends StripeResource {
   ): Promise<Response<AccountNotice>> {
     return this._makeRequest(
       'POST',
-      `/v1/account_notices/${id}`,
+      `/v1/account_notices/${encodeURIComponent(id)}`,
       params,
       options
     ) as any;

src/resources/Accounts.ts

@@ -38,7 +38,7 @@ export class AccountResource extends StripeResource {
   ): Promise<Response<DeletedAccount>> {
     return this._makeRequest(
       'DELETE',
-      `/v1/accounts/${id}`,
+      `/v1/accounts/${encodeURIComponent(id)}`,
       params,
       options
     ) as any;
@@ -84,7 +84,7 @@ export class AccountResource extends StripeResource {
   ): Promise<Response<Account>> {
     return this._makeRequest(
       'POST',
-      `/v1/accounts/${id}`,
+      `/v1/accounts/${encodeURIComponent(id)}`,
       params,
       options
     ) as any;
@@ -135,7 +135,7 @@ export class AccountResource extends StripeResource {
   ): Promise<Response<Account>> {
     return this._makeRequest(
       'POST',
-      `/v1/accounts/${id}/reject`,
+      `/v1/accounts/${encodeURIComponent(id)}/reject`,
       params,
       options
     ) as any;
@@ -208,7 +208,7 @@ export class AccountResource extends StripeResource {
   ): ApiListPromise<Capability> {
     return this._makeRequest(
       'GET',
-      `/v1/accounts/${id}/capabilities`,
+      `/v1/accounts/${encodeURIComponent(id)}/capabilities`,
       params,
       options,
       {
@@ -227,7 +227,9 @@ export class AccountResource extends StripeResource {
   ): Promise<Response<Capability>> {
     return this._makeRequest(
       'GET',
-      `/v1/accounts/${accountId}/capabilities/${id}`,
+      `/v1/accounts/${encodeURIComponent(
+        accountId
+      )}/capabilities/${encodeURIComponent(id)}`,
       params,
       options
     ) as any;
@@ -243,7 +245,9 @@ export class AccountResource extends StripeResource {
   ): Promise<Response<Capability>> {
     return this._makeRequest(
       'POST',
-      `/v1/accounts/${accountId}/capabilities/${id}`,
+      `/v1/accounts/${encodeURIComponent(
+        accountId
+      )}/capabilities/${encodeURIComponent(id)}`,
       params,
       options
     ) as any;
@@ -259,7 +263,9 @@ export class AccountResource extends StripeResource {
   ): Promise<Response<DeletedExternalAccount>> {
     return this._makeRequest(
       'DELETE',
-      `/v1/accounts/${accountId}/external_accounts/${id}`,
+      `/v1/accounts/${encodeURIComponent(
+        accountId
+      )}/external_accounts/${encodeURIComponent(id)}`,
       params,
       options
     ) as any;
@@ -275,7 +281,9 @@ export class AccountResource extends StripeResource {
   ): Promise<Response<ExternalAccount>> {
     return this._makeRequest(
       'GET',
-      `/v1/accounts/${accountId}/external_accounts/${id}`,
+      `/v1/accounts/${encodeURIComponent(
+        accountId
+      )}/external_accounts/${encodeURIComponent(id)}`,
       params,
       options
     ) as any;
@@ -298,7 +306,9 @@ export class AccountResource extends StripeResource {
   ): Promise<Response<ExternalAccount>> {
     return this._makeRequest(
       'POST',
-      `/v1/accounts/${accountId}/external_accounts/${id}`,
+      `/v1/accounts/${encodeURIComponent(
+        accountId
+      )}/external_accounts/${encodeURIComponent(id)}`,
       params,
       options
     ) as any;
@@ -313,7 +323,7 @@ export class AccountResource extends StripeResource {
   ): ApiListPromise<ExternalAccount> {
     return this._makeRequest(
       'GET',
-      `/v1/accounts/${id}/external_accounts`,
+      `/v1/accounts/${encodeURIComponent(id)}/external_accounts`,
       params,
       options,
       {
@@ -331,7 +341,7 @@ export class AccountResource extends StripeResource {
   ): Promise<Response<ExternalAccount>> {
     return this._makeRequest(
       'POST',
-      `/v1/accounts/${id}/external_accounts`,
+      `/v1/accounts/${encodeURIComponent(id)}/external_accounts`,
       params,
       options
     ) as any;
@@ -348,7 +358,7 @@ export class AccountResource extends StripeResource {
   ): Promise<Response<LoginLink>> {
     return this._makeRequest(
       'POST',
-      `/v1/accounts/${id}/login_links`,
+      `/v1/accounts/${encodeURIComponent(id)}/login_links`,
       params,
       options
     ) as any;
@@ -364,7 +374,9 @@ export class AccountResource extends StripeResource {
   ): Promise<Response<DeletedPerson>> {
     return this._makeRequest(
       'DELETE',
-      `/v1/accounts/${accountId}/persons/${id}`,
+      `/v1/accounts/${encodeURIComponent(
+        accountId
+      )}/persons/${encodeURIComponent(id)}`,
       params,
       options
     ) as any;
@@ -380,7 +392,9 @@ export class AccountResource extends StripeResource {
   ): Promise<Response<Person>> {
     return this._makeRequest(
       'GET',
-      `/v1/accounts/${accountId}/persons/${id}`,
+      `/v1/accounts/${encodeURIComponent(
+        accountId
+      )}/persons/${encodeURIComponent(id)}`,
       params,
       options
     ) as any;
@@ -396,7 +410,9 @@ export class AccountResource extends StripeResource {
   ): Promise<Response<Person>> {
     return this._makeRequest(
       'POST',
-      `/v1/accounts/${accountId}/persons/${id}`,
+      `/v1/accounts/${encodeURIComponent(
+        accountId
+      )}/persons/${encodeURIComponent(id)}`,
       params,
       options
     ) as any;
@@ -411,7 +427,7 @@ export class AccountResource extends StripeResource {
   ): ApiListPromise<Person> {
     return this._makeRequest(
       'GET',
-      `/v1/accounts/${id}/persons`,
+      `/v1/accounts/${encodeURIComponent(id)}/persons`,
       params,
       options,
       {
@@ -429,7 +445,7 @@ export class AccountResource extends StripeResource {
   ): Promise<Response<Person>> {
     return this._makeRequest(
       'POST',
-      `/v1/accounts/${id}/persons`,
+      `/v1/accounts/${encodeURIComponent(id)}/persons`,
       params,
       options
     ) as any;
@@ -444,7 +460,7 @@ export class AccountResource extends StripeResource {
   ): Promise<Response<AccountSignals>> {
     return this._makeRequest(
       'GET',
-      `/v1/accounts/${id}/signals`,
+      `/v1/accounts/${encodeURIComponent(id)}/signals`,
       params,
       options
     ) as any;