Provide an API version constant for the types

[billinghamj]

The readme mentions:

The type declarations in @stripe/stripe-js for these objects in will always track the latest version of the Stripe API.

It'd be helpful if there was an exported constant providing that version, to ensure we don't hardcode the current version, having the types move to a new version, and unknowingly having a mismatch

[fruchtose-stripe]

Thanks for the question. This is an interesting idea. How would the use of a version export work within your codebase? I'm not sure I understand how you would like to use this information. If you hardcode an old version of the Stripe API and try to use a new version of the TypeScript definitions with incompatible types, then tsc will report an error, right? Or if you update the types to match those of the new version, what is the reason you would you hardcode the old API version?

[billinghamj]

Ah the issue is that our version of stripe-js is continually updated by Dependabot, but we have no way to know whether the API version has been updated at the same time. We'd like to ensure that the API version and the types are always in lockstep.

It seems that is most easily achieved by getting the API version from this library, alongside the types.

We then pass the API version to our backend when generating ephemeral keys, and we'd provide it into options.apiVersion to ensure the actual data matches the types too (it might also be worthwhile doing this automatically in a future v3 of this library, as TypeScript is strongly typed and matching the behavior of other strongly typed Stripe libraries would be helpful)

Also for general context, we use stripe-js in an Expo app, and the same single piece of code also uses stripe-react-native and exposes a single consistent interface (basically stripe.native.tsx & stripe.web.tsx). Not super relevant to this ask though

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[billinghamj]

Not stale

[billinghamj]

What 😂

@fruchtose-stripe Could you please reopen? The bot ignored the bump

[fruchtose-stripe]

Sorry about that, I forgot to remove the stale label.

[cbala-stripe]

Does it work for you to import a constant type of the latest version? If so, you can do this:

import type {Stripe} from 'stripe';

type LatestApiVersion = Stripe.LatestApiVersion;

[billinghamj]

That sounds helpful, but the actual types are separate from the ones in this package. The key thing we need is the API version that was used to generate the types in this package

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[billinghamj]

Not stale :\

[madhav-stripe]

@billinghamj sorry for getting back to you late. Our team is actively trying to find the best solution that works for you and also for our library.

We're trying to better understand what your use case is. I'm going to try to explain what I understand but feel free to correct me if I am wrong.

Context
On the backend you pass in an apiVersion to ensure that the data being returned from the library is in an expected shape. You also do the same on the frontend using options.apiVersion.

Problem
The problem that you are facing is this part:

The type declarations in @stripe/stripe-js for these objects in will always track the latest version of the Stripe API.

If you are passing in an apiVersion with stripe-js and Dependabot upgrades stripe.js automatically, stripe.js might use a new version of the API (with new types) but you will still be using the older version of the API (specified via options.apiVersion). This mismatch will cause an error.

Please let me know if I've understood your problem correctly. If so, I've provided some potential solutions below.

Solutions

1. Expose a constant from our library that expresses most recent version of the API that the types are defined on (your suggestion from this issue)
2. Always use the latest version of the API when using stripe-js. Is there a reason why you can't always use the most recent version of the stripe-api? (by not passing in a version via options)
3. Rely on SemVer. We try our best to maintain semantic versioning when publishing updates to this library. New versions of stripe.js that have a minor or patch version are not breaking changes, and should not break the types in anyway (only fix them or add new fields). If you use a specific version, you should be okay to use all future versions of stripe-js until a breaking change is released.

Let me know if any of these work for your use-case, if not we'd be happy to take another look at it :)

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[billinghamj]

Sorry I think I missed your response!

Yes that's right, and indeed we're keen on solution #1

Solution #2 I think doesn't resolve the issue, because Stripe has backend APIs that require you to specify the API version - e.g. for the customer ephemeral key. (I appreciate that stripe-js doesn't use that currently, but stripe-react-native does, and we are using them together in a single Expo integration.)

Solution #3 is a fair point, though when Dependabot opens a PR with a major update to stripe-js, we'd still need to remember that there's something else we need to keep in sync. I don't think it's likely it'd be clear that was a key dependency without it being consistently called out in the list of breaking changes

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[billinghamj]

Not stale

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[billinghamj]

Not stale