Add WinterTC compatibility ESLint rule#2715
Merged
Merged
Conversation
…ed code stripe-node must run across Node.js, browsers, Deno, Bun, and Cloudflare Workers. This adds a custom ESLint rule that enforces the WinterTC Minimum Common Web Platform API spec (ECMA-429) by flagging Node.js built-in module imports, Node-specific globals (Buffer, process, etc.), and NodeJS.* type references in shared source files. Node-specific platform files (Node*.ts, stripe.*.node.ts) are excluded. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Committed-By-Agent: claude
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Committed-By-Agent: claude
This type is portable across all runtimes — it resolves to NodeJS.Timeout on Node and number elsewhere. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Committed-By-Agent: claude
Buffer extends Uint8Array, so removing it from the union is type-compatible — Node.js callers passing a Buffer still satisfy the Uint8Array branch. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Committed-By-Agent: claude
- Add emitWarning(), getEnv(), getRuntimeVersion() to PlatformFunctions base class with cross-runtime defaults (console.warn, null, null) - NodePlatformFunctions overrides with process.emitWarning, process.env, process.version - Move aiAgent/USER_AGENT initialization from static class properties into Stripe.initialize(), which receives the platform functions instance - Remove emitWarning and determineProcessUserAgentProperties from utils.ts - RequestSender calls emitWarning through platform functions - Fixes existing bug: emitWarning would crash on non-Node runtimes because it checked typeof process.emitWarning without first checking typeof process Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Committed-By-Agent: claude
These Node.js types are part of the public API surface and cannot be removed without a major version bump: - http.Agent in StripeConfig (DEVSDK-3114) - EventEmitter in StreamingFile and PlatformFunctions (DEVSDK-3113) - NodeJS.ReadableStream in StripeStreamResponse and HttpClient (DEVSDK-3112) Each suppression has a TODO referencing the Jira ticket for the next major version. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Committed-By-Agent: claude
- Rename origAI_AGENT to origAiAgentStatic (naming-convention rule) - Remove TODO prefix from DEVSDK ticket comments (no-warning-comments rule) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Committed-By-Agent: claude
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Committed-By-Agent: claude
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Committed-By-Agent: claude
prathmesh-stripe
approved these changes
May 15, 2026
prathmesh-stripe
left a comment
Contributor
There was a problem hiding this comment.
Just one comment, rest of this look great! Thanks for adding this.
This was referenced May 20, 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
2 participants
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?
stripe-node must run across Node.js, browsers, Deno, Bun, and Cloudflare Workers. Today there's no automated way to catch Node.js-specific API usage leaking into shared code. This adds a lint rule based on the WinterTC Minimum Common Web Platform API spec (ECMA-429) to flag these issues at development time.
No existing ESLint plugin covers this spec — we searched npm, GitHub, and the WinterTC55 org. This is a custom rule.
What?
New ESLint rule (
eslint-rules/wintertc-compat.js):http,crypto,events, etc.)Buffer,process,__dirname,__filename,global,require,module,exports)NodeJS.*type references (NodeJS.Timeout,NodeJS.ReadableStream, etc.)src/**/*.ts, disabled for Node-specific platform files (Node*.ts,stripe.*.node.ts)--rulesdir eslint-rulesto the lint command in the JustfileFixes (non-breaking):
NodeJS.TimeoutwithReturnType<typeof setTimeout>(portable across runtimes)BufferfromFileDataunion type (Buffer extends Uint8Array, so callers are unaffected)process-dependent code (emitWarning,detectAIAgent,determineProcessUserAgentProperties) into platform functions viaStripe.initialize(). Also fixes an existing bug whereemitWarningwould crash on non-Node runtimes.emitWarning(),getEnv(),getRuntimeVersion()toPlatformFunctionsbase class with cross-runtime defaultsDeferred to next major (public API types):
NodeJS.ReadableStreaminStripeStreamResponseandHttpClient(DEVSDK-3112)EventEmitterinStreamingFileandPlatformFunctions(DEVSDK-3113)http.AgentinStripeConfig(DEVSDK-3114)These are suppressed with
eslint-disable+ TODO comments referencing the tickets.Other:
no-warning-commentsfromerrortowarnso TODO comments don't block CIgetEnv()/getRuntimeVersion()for Deno, Bun, and WorkersSee Also