Specify a major release for `apiVersion`

[bryfox]

Is your feature request related to a problem? Please describe.

I'd like to pin my Stripe client to the latest major version (e.g., "acacia"). Right now, I can either declare a specific monthly version, requiring intervention on each automated dependency update, or place no restriction at all. I understand that the SDK only declares types for the latest versions, but my code will typically not encounter problems, and monthly updates are documented as backwards-compatible.

Put another way: I'd like dependabot to keep Stripe automatically updated with periodic updates (bug fixes, etc.) but require manual intervention to upgrade to the next major version.

Describe the solution you'd like

// Something like
type LatestApiVersion = "2025-02-24.acacia" | "acacia"

// So that I can call
new Stripe(KEY, { apiVersion: "acacia" })

Describe alternatives you've considered

• Adding (to my code) a complicated type check & test verifying that LatestApiVersion matches 'acacia', removing apiVersion config
• Manually upgrading Stripe and excluding from dependabot updates

Additional context

No response

[ramya-stripe]

Hey @bryfox

As of version 12 of the Node SDK, we are pinning the API version used. See changelog for v12

A new major version of the API like acacia is accompanied by a new major version of the SDK.
For example, all versions 17.x.x of the Node SDK map to the acacia release
17.0.0 -> 2024-09-30.acacia
17.3.0 -> 2024-10-28.acacia
17.4.0 -> 2024-11-20.acacia
And so on

You could update your package.json to use ^17.0.0 and be ensured to stay on the latest version of the SDK that maps to acacia. Will that work for you?

[bryfox]

Thanks — that's good to know. We could constrain dependabot to a major version. The advantage of being able to specify the major version in app code is that we'd get periodic (annual) automated PRs which could be reviewed and accepted by changing the version string, keeping us eventually up-to-date with major versions. In the scheme of things, this change would be only a small quality-of-life improvement, so I'm happy to close the issue if it's not something you're interested in.

[xavdid-stripe]

We've surfaced it as an API-level request, but Ramya's suggestion above is probably the best approach for now. You're welcome to close if you'd like, or we can leave it open as a feature request in case anyone else comes by.