Add type safety to Stripe constructor config (no runtime change)#2667
Merged
mbroshi-stripe merged 4 commits intomasterfrom Apr 8, 2026
Merged
Add type safety to Stripe constructor config (no runtime change)#2667mbroshi-stripe merged 4 commits intomasterfrom
mbroshi-stripe merged 4 commits intomasterfrom
Conversation
The constructor's second parameter was typed as Record<string, unknown>, which provided no compile-time type checking, autocomplete, or documentation on hover. This changes it to use the existing StripeConfig interface, giving TypeScript users proper type safety. Also adds the missing `authenticator` property to StripeConfig (it was accepted at runtime but absent from the public type) and aligns UserProvidedConfig.port to accept string | number to match StripeConfig. Fixes #2665 (partially — addresses the type safety complaint). Co-Authored-By: Claude Opus 4.6 <[email protected]> Committed-By-Agent: claude
- Type `API_VERSION` as `typeof ApiVersion` to retain the literal type, so `Stripe.API_VERSION` is assignable to `StripeConfig.apiVersion`. - Accept `StripeContext` in `StripeConfig.stripeContext` to match `UserProvidedConfig` and runtime behavior. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> Committed-By-Agent: claude
There was a problem hiding this comment.
Pull request overview
Improves TypeScript type-safety for the Stripe constructor config by switching from a permissive Record<string, unknown> to the public StripeConfig type, aligning runtime-accepted config options with the declared types, and adding a compile-time type test.
Changes:
- Updated
Stripeconstructor config parameter types toStripeConfig(core + ESM Node + CJS Node wrapper) and refined internal config parsing typing. - Added
authenticatortoStripeConfig, widenedstripeContext, and alignedUserProvidedConfig.portwithStripeConfig.port. - Added a TypeScript compile-time test ensuring unknown constructor config properties are rejected.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| testProjects/types/typescriptTest.ts | Adds a @ts-expect-error type test for unknown constructor config properties. |
| src/Types.ts | Widens UserProvidedConfig.port to string | number. |
| src/stripe.esm.node.ts | Uses StripeConfig for constructor config + types Stripe.API_VERSION as literal-preserving. |
| src/stripe.core.ts | Uses StripeConfig for constructor config + types Stripe.API_VERSION as literal-preserving. |
| src/stripe.cjs.node.ts | Updates the CJS callable wrapper signature to accept StripeConfig. |
| src/lib.ts | Extends StripeConfig with authenticator and widens stripeContext to accept StripeContext. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Missed this entry point in the initial change. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> Committed-By-Agent: claude
xavdid
approved these changes
Apr 7, 2026
Member
There was a problem hiding this comment.
This looks good but I'd just make it clear in the title/changelog that nothing about the runtime behavior has changed: we used to have types for this function, we accidentally stop applying them, and now we're fixing that. Now they look like they did before the change:
Line 37 in 0291e44
prathmesh-stripe
approved these changes
Apr 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why?
The
Stripeconstructor's second parameter was typed asRecord<string, unknown>, which meant TypeScript users got no autocomplete, no excess property checking, and no documentation on hover. This was reported in #2665. This was caused by a type regression in our recent type improvements (compare tostripe-node/types/lib.d.ts
Line 37 in 0291e44
What?
Record<string, unknown>toStripeConfigacross all entry points (stripe.core.ts,stripe.esm.node.ts,stripe.cjs.node.ts)authenticatorproperty toStripeConfig(it was accepted at runtime viaALLOWED_CONFIG_PROPERTIESbut absent from the public type)UserProvidedConfig.porttype tostring | numberto matchStripeConfig.portStripe.API_VERSIONastypeof ApiVersionso it retains the literal type and is assignable toStripeConfig.apiVersionStripeContextinStripeConfig.stripeContextto matchUserProvidedConfigand runtime behaviorSee Also
Changelog
Stripeconstructor config parameter to useStripeConfigtype instead ofRecord<string, unknown>, restoring compile-time type safety.authenticatorproperty toStripeConfig.Stripe.API_VERSIONto retain the literal API version type.StripeConfig.stripeContextto acceptStripeContextobjects in addition to strings.