feat(backend): Add billing api and an endpoint for fetching plans #6449
Conversation
🦋 Changeset detectedLatest commit: b5d9a51 The changes in this PR will be included in the next version bump. This PR includes changesets to release 11 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
!snapshot |
|
Hey @panteliselef - the snapshot version command generated the following package versions:
Tip: Use the snippet copy button below to quickly install the required packages. npm i @clerk/agent-toolkit@0.1.16-snapshot.v20250731165820 --save-exact
npm i @clerk/astro@2.10.13-snapshot.v20250731165820 --save-exact
npm i @clerk/backend@2.7.0-snapshot.v20250731165820 --save-exact
npm i @clerk/chrome-extension@2.5.15-snapshot.v20250731165820 --save-exact
npm i @clerk/clerk-js@5.79.0-snapshot.v20250731165820 --save-exact
npm i @clerk/elements@0.23.48-snapshot.v20250731165820 --save-exact
npm i @clerk/clerk-expo@2.14.14-snapshot.v20250731165820 --save-exact
npm i @clerk/expo-passkeys@0.3.25-snapshot.v20250731165820 --save-exact
npm i @clerk/express@1.7.15-snapshot.v20250731165820 --save-exact
npm i @clerk/fastify@2.4.15-snapshot.v20250731165820 --save-exact
npm i @clerk/localizations@3.20.6-snapshot.v20250731165820 --save-exact
npm i @clerk/nextjs@6.28.1-snapshot.v20250731165820 --save-exact
npm i @clerk/nuxt@1.8.1-snapshot.v20250731165820 --save-exact
npm i @clerk/clerk-react@5.38.1-snapshot.v20250731165820 --save-exact
npm i @clerk/react-router@1.8.9-snapshot.v20250731165820 --save-exact
npm i @clerk/remix@4.10.9-snapshot.v20250731165820 --save-exact
npm i @clerk/shared@3.17.0-snapshot.v20250731165820 --save-exact
npm i @clerk/tanstack-react-start@0.21.5-snapshot.v20250731165820 --save-exact
npm i @clerk/testing@1.10.9-snapshot.v20250731165820 --save-exact
npm i @clerk/themes@2.4.4-snapshot.v20250731165820 --save-exact
npm i @clerk/types@4.72.0-snapshot.v20250731165820 --save-exact
npm i @clerk/vue@1.9.1-snapshot.v20250731165820 --save-exact |
📝 WalkthroughWalkthroughThis change introduces new commerce-related resource types and API endpoints to the backend package. A new Estimated code review effort🎯 3 (Moderate) | ⏱️ ~15–20 minutes
Note 🔌 MCP (Model Context Protocol) integration is now available in Early Access!Pro users can now connect to remote MCP servers under the Integrations page to get reviews and chat conversations that understand additional development context. 📜 Recent review detailsConfiguration used: CodeRabbit UI ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (5)
🚧 Files skipped from review as they are similar to previous changes (5)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
There was a problem hiding this comment.
Actionable comments posted: 9
🔭 Outside diff range comments (2)
packages/backend/src/api/resources/JSON.ts (2)
825-847: Add JSDoc documentation for CommercePlanJSON interfaceThe interface should have JSDoc documentation describing its purpose and clarifying fields like
interval.+/** + * JSON representation of a commerce subscription plan + */ export interface CommercePlanJSON extends ClerkResourceJSON {
1-936: Security review and tests neededPlease address two critical areas before merging:
Security Review
Tag @clerk/security for a dedicated review of all new commerce/payment logic.Add Missing Tests
No tests cover the new billing endpoints or model deserialization. At a minimum, add unit tests for:
•BillingAPI.getPlanListinpackages/backend/src/api/endpoints/BillingApi.ts
•CommercePlan.fromJSONinpackages/backend/src/api/resources/CommercePlan.ts
•Feature.fromJSONintegration withCommercePlan.fromJSON
• Error/edge-case handling (e.g. empty plan list, malformed JSON)
🧹 Nitpick comments (3)
packages/backend/src/api/resources/index.ts (1)
60-60: Consider alphabetical ordering of exports.While the export is correct, consider placing it in alphabetical order with other resource exports (around line 7-8 after Client exports) for better maintainability.
export * from './Client'; export * from './CnameTarget'; +export * from './CommercePlan'; export * from './Cookies';And remove from the current location:
export * from './WaitlistEntry'; export * from './Web3Wallet'; -export * from './CommercePlan';packages/backend/src/api/resources/Feature.ts (1)
12-14: Consider input validation for the fromJSON method.The method assumes all required properties exist in the JSON data. Consider adding validation to provide better error messages for malformed data.
static fromJSON(data: FeatureJSON): Feature { + if (!data.id || !data.name || !data.slug) { + throw new Error('Invalid feature data: missing required fields'); + } return new Feature(data.id, data.name, data.description, data.slug, data.avatar_url); }packages/backend/src/api/resources/CommercePlan.ts (1)
71-79: Extract formatAmountJSON for better modularityThe
formatAmountJSONfunction could be useful elsewhere and should be extracted as a private static method or utility function.+ private static formatAmountJSON(fee: CommercePlanJSON['fee']): CommerceFee { + return { + amount: fee.amount, + amountFormatted: fee.amount_formatted, + currency: fee.currency, + currencySymbol: fee.currency_symbol, + }; + } + static fromJSON(data: CommercePlanJSON): CommercePlan { - const formatAmountJSON = (fee: CommercePlanJSON['fee']) => { - return { - amount: fee.amount, - amountFormatted: fee.amount_formatted, - currency: fee.currency, - currencySymbol: fee.currency_symbol, - }; - }; return new CommercePlan(And update the usage:
- formatAmountJSON(data.fee), - formatAmountJSON(data.annual_fee), - formatAmountJSON(data.annual_monthly_fee), + CommercePlan.formatAmountJSON(data.fee), + CommercePlan.formatAmountJSON(data.annual_fee), + CommercePlan.formatAmountJSON(data.annual_monthly_fee),
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (9)
.changeset/early-bats-shout.md(1 hunks)packages/backend/src/api/endpoints/BillingApi.ts(1 hunks)packages/backend/src/api/factory.ts(2 hunks)packages/backend/src/api/resources/CommercePlan.ts(1 hunks)packages/backend/src/api/resources/Deserializer.ts(2 hunks)packages/backend/src/api/resources/Feature.ts(1 hunks)packages/backend/src/api/resources/JSON.ts(5 hunks)packages/backend/src/api/resources/index.ts(1 hunks)packages/backend/src/index.ts(1 hunks)
🧰 Additional context used
📓 Path-based instructions (10)
.changeset/**
📄 CodeRabbit Inference Engine (.cursor/rules/monorepo.mdc)
Automated releases must use Changesets.
Files:
.changeset/early-bats-shout.md
**/*.{js,jsx,ts,tsx}
📄 CodeRabbit Inference Engine (.cursor/rules/development.mdc)
**/*.{js,jsx,ts,tsx}: All code must pass ESLint checks with the project's configuration
Follow established naming conventions (PascalCase for components, camelCase for variables)
Maintain comprehensive JSDoc comments for public APIs
Use dynamic imports for optional features
All public APIs must be documented with JSDoc
Provide meaningful error messages to developers
Include error recovery suggestions where applicable
Log errors appropriately for debugging
Lazy load components and features when possible
Implement proper caching strategies
Use efficient data structures and algorithms
Profile and optimize critical paths
Validate all inputs and sanitize outputs
Implement proper logging with different levels
Files:
packages/backend/src/api/endpoints/BillingApi.tspackages/backend/src/api/factory.tspackages/backend/src/api/resources/Feature.tspackages/backend/src/api/resources/CommercePlan.tspackages/backend/src/api/resources/Deserializer.tspackages/backend/src/api/resources/index.tspackages/backend/src/api/resources/JSON.tspackages/backend/src/index.ts
**/*.{js,jsx,ts,tsx,json,css,scss,md,yaml,yml}
📄 CodeRabbit Inference Engine (.cursor/rules/development.mdc)
Use Prettier for consistent code formatting
Files:
packages/backend/src/api/endpoints/BillingApi.tspackages/backend/src/api/factory.tspackages/backend/src/api/resources/Feature.tspackages/backend/src/api/resources/CommercePlan.tspackages/backend/src/api/resources/Deserializer.tspackages/backend/src/api/resources/index.tspackages/backend/src/api/resources/JSON.tspackages/backend/src/index.ts
packages/**/*.{ts,tsx}
📄 CodeRabbit Inference Engine (.cursor/rules/development.mdc)
TypeScript is required for all packages
Files:
packages/backend/src/api/endpoints/BillingApi.tspackages/backend/src/api/factory.tspackages/backend/src/api/resources/Feature.tspackages/backend/src/api/resources/CommercePlan.tspackages/backend/src/api/resources/Deserializer.tspackages/backend/src/api/resources/index.tspackages/backend/src/api/resources/JSON.tspackages/backend/src/index.ts
packages/**/*.{ts,tsx,d.ts}
📄 CodeRabbit Inference Engine (.cursor/rules/development.mdc)
Packages should export TypeScript types alongside runtime code
Files:
packages/backend/src/api/endpoints/BillingApi.tspackages/backend/src/api/factory.tspackages/backend/src/api/resources/Feature.tspackages/backend/src/api/resources/CommercePlan.tspackages/backend/src/api/resources/Deserializer.tspackages/backend/src/api/resources/index.tspackages/backend/src/api/resources/JSON.tspackages/backend/src/index.ts
**/*.{ts,tsx}
📄 CodeRabbit Inference Engine (.cursor/rules/development.mdc)
Use proper TypeScript error types
**/*.{ts,tsx}: Always define explicit return types for functions, especially public APIs
Use proper type annotations for variables and parameters where inference isn't clear
Avoidanytype - preferunknownwhen type is uncertain, then narrow with type guards
Useinterfacefor object shapes that might be extended
Usetypefor unions, primitives, and computed types
Preferreadonlyproperties for immutable data structures
Useprivatefor internal implementation details
Useprotectedfor inheritance hierarchies
Usepublicexplicitly for clarity in public APIs
Preferreadonlyfor properties that shouldn't change after construction
Prefer composition and interfaces over deep inheritance chains
Use mixins for shared behavior across unrelated classes
Implement dependency injection for loose coupling
Let TypeScript infer when types are obvious
Useconst assertionsfor literal types:as const
Usesatisfiesoperator for type checking without widening
Use mapped types for transforming object types
Use conditional types for type-level logic
Leverage template literal types for string manipulation
Use ES6 imports/exports consistently
Use default exports sparingly, prefer named exports
Use type-only imports:import type { ... } from ...
Noanytypes without justification
Proper error handling with typed errors
Consistent use ofreadonlyfor immutable data
Proper generic constraints
No unused type parameters
Proper use of utility types instead of manual type construction
Type-only imports where possible
Proper tree-shaking friendly exports
No circular dependencies
Efficient type computations (avoid deep recursion)
Files:
packages/backend/src/api/endpoints/BillingApi.tspackages/backend/src/api/factory.tspackages/backend/src/api/resources/Feature.tspackages/backend/src/api/resources/CommercePlan.tspackages/backend/src/api/resources/Deserializer.tspackages/backend/src/api/resources/index.tspackages/backend/src/api/resources/JSON.tspackages/backend/src/index.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit Inference Engine (.cursor/rules/monorepo.mdc)
Support multiple Clerk environment variables (CLERK_, NEXT_PUBLIC_CLERK_, etc.) for configuration.
Files:
packages/backend/src/api/endpoints/BillingApi.tspackages/backend/src/api/factory.tspackages/backend/src/api/resources/Feature.tspackages/backend/src/api/resources/CommercePlan.tspackages/backend/src/api/resources/Deserializer.tspackages/backend/src/api/resources/index.tspackages/backend/src/api/resources/JSON.tspackages/backend/src/index.ts
**/*
⚙️ CodeRabbit Configuration File
**/*: If there are no tests added or modified as part of the PR, please suggest that tests be added to cover the changes.Whenever reviewing a pull request, if there are any changes that could impact security, always tag
@clerk/securityin the PR.Security-impacting changes include, but are not limited to:
- Changes to authentication logic or mechanisms (e.g. login, session handling, token issuance)
- Any modification to access control, authorization checks, or role-based permissions
- Introduction or modification of hashing algorithms, signature verification, or cryptographic primitives
- Handling of sensitive data (e.g. passwords, tokens, secrets, PII)
- Integration with external identity providers (e.g. SSO, OAuth, OpenID Connect)
- Modifications to security headers, cookie flags, CORS policies, or CSRF protections
- Bypass mechanisms (e.g. feature flags, testing overrides) that could weaken protections
- Changes to rate limiting, abuse prevention, or input validation
If you're unsure whether a change is security-relevant, err on the side of caution and tag
@clerk/security.Any time that you tag
@clerk/security, please do so explicitly in a code comment, rather than within a collapsed section in a coderabbit comment, such as the "recent review details" section. If you do use the team name in any thinking or non-direct-code-comment content, it can be referred to as "clerk security team" to avoid accidentally printing the tag which sends a notification to the team.
Files:
packages/backend/src/api/endpoints/BillingApi.tspackages/backend/src/api/factory.tspackages/backend/src/api/resources/Feature.tspackages/backend/src/api/resources/CommercePlan.tspackages/backend/src/api/resources/Deserializer.tspackages/backend/src/api/resources/index.tspackages/backend/src/api/resources/JSON.tspackages/backend/src/index.ts
packages/**/index.{js,ts}
📄 CodeRabbit Inference Engine (.cursor/rules/development.mdc)
Use tree-shaking friendly exports
Files:
packages/backend/src/api/resources/index.tspackages/backend/src/index.ts
**/index.ts
📄 CodeRabbit Inference Engine (.cursor/rules/react.mdc)
Use index.ts files for clean imports but avoid deep barrel exports
Avoid barrel files (index.ts re-exports) as they can cause circular dependencies
Files:
packages/backend/src/api/resources/index.tspackages/backend/src/index.ts
🔇 Additional comments (5)
packages/backend/src/api/resources/Deserializer.ts (2)
40-41: LGTM! Imports are properly added.The new resource imports follow the established pattern and are correctly positioned alphabetically.
184-187: LGTM! Deserialization cases are correctly implemented.The new switch cases for CommercePlan and Feature follow the established pattern and properly call the fromJSON static methods.
packages/backend/src/api/factory.ts (2)
32-32: LGTM! Import is properly positioned.The BillingAPI import follows the established alphabetical ordering pattern.
56-56: LGTM! Billing API integration follows established pattern.The billing API is correctly instantiated and positioned alphabetically in the returned client object.
Note: Since this introduces billing/commerce functionality that handles financial data, please ensure appropriate security reviews are conducted. @clerk/security should review these billing-related changes.
packages/backend/src/index.ts (1)
147-147: Export addition looks goodThe addition of
CommercePlanto the exported types is correct and follows the existing pattern.
@clerk/agent-toolkit
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/dev-cli
@clerk/elements
@clerk/clerk-expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/clerk-react
@clerk/react-router
@clerk/remix
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/themes
@clerk/types
@clerk/upgrade
@clerk/vue
commit: |
| @@ -846,17 +833,28 @@ export interface CommercePlanJSON { | |||
| is_recurring: boolean; | |||
| amount: number; | |||
| period: 'month' | 'annual'; | |||
There was a problem hiding this comment.
I'm working on removing period and interval from plans now and also the "top level amounts", so this may need a refactor soon if merged before my change.
There was a problem hiding this comment.
Handled here. This PR will get merged only after BAPI changes are in effect.
There was a problem hiding this comment.
I was also referring to the plans.period and plans.interval thats being added here
There was a problem hiding this comment.
Those should be persisted, as they affect the webhooks that can be already consumed by our customers.
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (1)
packages/backend/src/api/resources/JSON.ts (1)
817-823: Add JSDoc documentation for FeatureJSON interface.The new interface should have JSDoc documentation to follow the coding guidelines requiring comprehensive JSDoc comments for public APIs.
+/** + * JSON representation of a plan feature + */ export interface FeatureJSON extends ClerkResourceJSON {
🧹 Nitpick comments (1)
packages/backend/src/api/resources/JSON.ts (1)
862-878: Consider consistency between inline plan object and CommercePlanJSON.The inline plan object structure differs from
CommercePlanJSONinterface:
- Uses primitive
amount: numberinstead ofCommerceFeeJSONstructure- Includes
periodandintervalfields not present inCommercePlanJSON- Missing
featuresarray and other fields fromCommercePlanJSONConsider whether this inconsistency is intentional or if alignment would improve maintainability.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
packages/backend/src/api/resources/JSON.ts(4 hunks)
🧰 Additional context used
📓 Path-based instructions (7)
**/*.{js,jsx,ts,tsx}
📄 CodeRabbit Inference Engine (.cursor/rules/development.mdc)
**/*.{js,jsx,ts,tsx}: All code must pass ESLint checks with the project's configuration
Follow established naming conventions (PascalCase for components, camelCase for variables)
Maintain comprehensive JSDoc comments for public APIs
Use dynamic imports for optional features
All public APIs must be documented with JSDoc
Provide meaningful error messages to developers
Include error recovery suggestions where applicable
Log errors appropriately for debugging
Lazy load components and features when possible
Implement proper caching strategies
Use efficient data structures and algorithms
Profile and optimize critical paths
Validate all inputs and sanitize outputs
Implement proper logging with different levels
Files:
packages/backend/src/api/resources/JSON.ts
**/*.{js,jsx,ts,tsx,json,css,scss,md,yaml,yml}
📄 CodeRabbit Inference Engine (.cursor/rules/development.mdc)
Use Prettier for consistent code formatting
Files:
packages/backend/src/api/resources/JSON.ts
packages/**/*.{ts,tsx}
📄 CodeRabbit Inference Engine (.cursor/rules/development.mdc)
TypeScript is required for all packages
Files:
packages/backend/src/api/resources/JSON.ts
packages/**/*.{ts,tsx,d.ts}
📄 CodeRabbit Inference Engine (.cursor/rules/development.mdc)
Packages should export TypeScript types alongside runtime code
Files:
packages/backend/src/api/resources/JSON.ts
**/*.{ts,tsx}
📄 CodeRabbit Inference Engine (.cursor/rules/development.mdc)
Use proper TypeScript error types
**/*.{ts,tsx}: Always define explicit return types for functions, especially public APIs
Use proper type annotations for variables and parameters where inference isn't clear
Avoidanytype - preferunknownwhen type is uncertain, then narrow with type guards
Useinterfacefor object shapes that might be extended
Usetypefor unions, primitives, and computed types
Preferreadonlyproperties for immutable data structures
Useprivatefor internal implementation details
Useprotectedfor inheritance hierarchies
Usepublicexplicitly for clarity in public APIs
Preferreadonlyfor properties that shouldn't change after construction
Prefer composition and interfaces over deep inheritance chains
Use mixins for shared behavior across unrelated classes
Implement dependency injection for loose coupling
Let TypeScript infer when types are obvious
Useconst assertionsfor literal types:as const
Usesatisfiesoperator for type checking without widening
Use mapped types for transforming object types
Use conditional types for type-level logic
Leverage template literal types for string manipulation
Use ES6 imports/exports consistently
Use default exports sparingly, prefer named exports
Use type-only imports:import type { ... } from ...
Noanytypes without justification
Proper error handling with typed errors
Consistent use ofreadonlyfor immutable data
Proper generic constraints
No unused type parameters
Proper use of utility types instead of manual type construction
Type-only imports where possible
Proper tree-shaking friendly exports
No circular dependencies
Efficient type computations (avoid deep recursion)
Files:
packages/backend/src/api/resources/JSON.ts
**/*.{js,ts,tsx,jsx}
📄 CodeRabbit Inference Engine (.cursor/rules/monorepo.mdc)
Support multiple Clerk environment variables (CLERK_, NEXT_PUBLIC_CLERK_, etc.) for configuration.
Files:
packages/backend/src/api/resources/JSON.ts
**/*
⚙️ CodeRabbit Configuration File
**/*: If there are no tests added or modified as part of the PR, please suggest that tests be added to cover the changes.Whenever reviewing a pull request, if there are any changes that could impact security, always tag
@clerk/securityin the PR.Security-impacting changes include, but are not limited to:
- Changes to authentication logic or mechanisms (e.g. login, session handling, token issuance)
- Any modification to access control, authorization checks, or role-based permissions
- Introduction or modification of hashing algorithms, signature verification, or cryptographic primitives
- Handling of sensitive data (e.g. passwords, tokens, secrets, PII)
- Integration with external identity providers (e.g. SSO, OAuth, OpenID Connect)
- Modifications to security headers, cookie flags, CORS policies, or CSRF protections
- Bypass mechanisms (e.g. feature flags, testing overrides) that could weaken protections
- Changes to rate limiting, abuse prevention, or input validation
If you're unsure whether a change is security-relevant, err on the side of caution and tag
@clerk/security.Any time that you tag
@clerk/security, please do so explicitly in a code comment, rather than within a collapsed section in a coderabbit comment, such as the "recent review details" section. If you do use the team name in any thinking or non-direct-code-comment content, it can be referred to as "clerk security team" to avoid accidentally printing the tag which sends a notification to the team.
Files:
packages/backend/src/api/resources/JSON.ts
🧬 Code Graph Analysis (1)
packages/backend/src/api/resources/JSON.ts (2)
packages/backend/src/index.ts (4)
ClerkResourceJSON(59-59)CommercePlanJSON(104-104)CommerceSubscriptionItemJSON(105-105)CommercePayerJSON(103-103)packages/types/src/json.ts (3)
ClerkResourceJSON(36-40)CommercePlanJSON(631-652)CommerceSubscriptionItemJSON(767-783)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)
- GitHub Check: Build Packages
- GitHub Check: Formatting | Dedupe | Changeset
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: semgrep/ci
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (4)
packages/backend/src/api/resources/JSON.ts (4)
72-73: LGTM! Object type additions are correctly implemented.The new entries for
CommercePlanandFeaturefollow the established naming conventions and align with the billing API functionality being introduced.
797-815: Well-structured internal interfaces for commerce data.The new internal interfaces follow TypeScript best practices:
CommercePayeeJSONproperly defines gateway information with appropriate literal typesCommerceFeeJSONreplacement forCommerceAmountJSONis more semantically clearCommerceTotalsJSONcorrectly composes the fee structure
825-841: Excellent refactoring of CommercePlanJSON interface.The interface improvements are well-designed:
- Consistent use of
CommerceFeeJSONfor financial data- Proper literal union type for
for_payer_type- Clean integration of the new
featuresarray- Removal of
instance_idaligns with the architectural changes
893-911: Improved structured data for payment attempt details.The enhanced inline objects provide better typed information:
failed_reasonnow includes bothcodeanddecline_codefor better error handlingpayment_sourceprovides comprehensive payment method details with proper typingThese changes improve API usability and type safety.
Description
Exposes BAPI endpoints related to billing under
clerkClient.billing.*.At this time we only expose
clerkClient.billing.getPlanList()that returns a paginated list of an instance's plans.Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change
Summary by CodeRabbit
New Features
Refactor