Feature request: support for multiple Stripe API types

[Unibozu]

Hi all,

I'm not so sure of the best way to reach out about a feature request so let me know if there is better.

I've noticed you bumped the Stripe API Version to 2020-03-02.

It would be amazing if there was a way for you to support multiple Stripe API types within a single repo so that we can continue upgrading the stripe-node SDK while using an older Stripe API version. It feels like you aren't too far away from this possibility considering your tooling with your openapi documentation.

Additionally, bumping the API version is currently a breaking change. I am unable to use this semver spec in package.json ^8.19.0 and issue a (supposedly safe) yarn upgrade stripe. Supporting multiple API versions would actually make it a BC change.

All the best

[rattrayalex-stripe]

Hi @Unibozu ,

We've spent a lot of time looking at supporting multiple API versions with stripe-node's TypeScript definitions. (To clarify for other readers, this library is compatible with all Stripe API versions, but the TypeScript definitions are only compatible with one: the latest).

Unfortunately, supporting multiple API versions presents several challenges. For our users, it would cause a great deal of package bloat to have full definitions for each change (getting clever with only the relevant changes presents several practical problems, but may be feasible at some point). Internally, we don't yet have the capability to generate accurate types for old api versions – they need to be kept up-to-date as we add new endpoints and parameters, which are available under both new and old API versions.

In terms of the breaking change, we see your point, and may shift to major versions for type-only changes (further feedback from the community welcome!).

I say type-only because, as documented in the readme you can add comments like // @ts-ignore stripe-version-2019-12-03 to the stripe instantiation and any places that the types differ, and upgrade your library version without any changes to your API version.

This isn't the greatest for TS users, but makes things much simpler for non-TS users (for whom this would not be a breaking change, or even a change at all). Feedback welcome on whether this is a dealbreaker.

Thanks!

[Unibozu]

Hi Alex,

Thanks for these details.

I had a look at your typings folder and it seems to be more than 1MB so I fully agree you can't include each API version with stripe.

We've had to use // @ts-ignore up until recently because we were on a 2017 API version for way too long. It works but it's a shame as we end up losing all key benefits of TS and it's not so easy in a codebase with strict coding standards (happened to us). Furthermore, you must have your team fully aware of the disparity between the types available (and contextual completion provided by your IDE) and the actual version of the Stripe API your app is using. That made changes to anything stripe-related a huge problem until we were able to upgrade to the latest API version. And to be frank I actually contemplated removing @types/stripe if we didn't upgrade (which is now impossible).

Perhaps the dealbreaker is that we can't remove the TS typings anymore. We've survived it but it was difficult, and seeing how you guys started to structure your new types when you took over from DefinitelyTyped made me excited to see this feature.

Perhaps a solution can exist by using a separate historical types package and generics? Now, this is a very rushed idea of a solution for the sake of the discussion, I haven't tested anything. TS users can include this package on demand and configure the relevant version of the API types, while non-TS users won't be affected. Versioning can mirror the date format of your API versioning too. You would also want to not force all TS users to use this either, so using a Generic with a default value can make this work.

npm install --save-dev stripe-types@2019.12.03

import {Stripg} from 'stripe';
import {StripeApiTypes} from 'stripe-types';

const stripe = new Stripe<StripeApiTypes>({ /* options */});

However, I am not sure how it would actually work with the resource namespacing that already exist in your lib and how it could affect our codebase.

Food for thoughts!

[jaytavares]

I'll second the partial solution of bumping major versions any time the LatestApiVersion changes. A release that drops support for an api version (even if it only affects the types) would seem to be a breaking change and require a major version bump according to the semver spec.

As of today, the following two commands, which should always work without issue, will eventually break your build (given enough time between them):

$ npm install stripe

$ npm update

This is because npm install defaults to "^[latest]" (e.g. "^8.132.0"). This allows minor and patch versions to be installed automatically since it is assumed they will not contain breaking changes; however, as you know, when api versions change, typescript compilation fails.

[ramya-stripe]

It would be amazing if there was a way for you to support multiple Stripe API types within a single repo so that we can continue upgrading the stripe-node SDK while using an older Stripe API version.

@Unibozu Can you please elaborate why you might want to upgrade the stripe-node SDK but not upgrade to the latest Stripe API version?

[Unibozu]

We had a codebase that was using multiple versions of the Stripe API.

The newer version was used for our Stipe Connect implementation while we kept our payments using a previous version to avoid having to make changes to it as we were upgrading to support newer functionalities of Connect.

Your API supports any concurrent version. Your client should as well.

Thinking outside of that specific use case, this will also help with keeping dependencies up to date. Especially if one of the deps from the stripe client has vulnerabilities.