chore(repo,types): Update billing-related types; hide "Type declaration" heading from typedoc output #6801
Conversation
…to aa/update-billing-jsdoc-comments
🦋 Changeset detectedLatest commit: cab9457 The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types 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 GitHub.
|
WalkthroughRemoves two TypeDoc link replacements; tweaks TypeDoc theme output to hide "Type declaration" headings and shorten union headings; renames a backend doc reference; adds BillingStatementGroup and a cancel(...) method on subscription items; and applies JSDoc/formatted comment refinements across several type files. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Dev as Developer
participant SDK as BillingSubscriptionItemResource (SDK)
participant API as Billing API
participant Svc as Subscription Service
Note over Dev,SDK: Cancel subscription item (new method)
Dev->>SDK: cancel(params)
SDK->>API: POST /subscription-items/:id/cancel
API->>Svc: request cancel for item id
Svc-->>API: DeletedObjectResource
API-->>SDK: DeletedObjectResource
SDK-->>Dev: Promise<DeletedObjectResource>
sequenceDiagram
autonumber
actor Dev as Consumer
participant API as Billing API
participant Store as Data Store
Note over Dev,API: Statement grouping returned as new type
Dev->>API: GET /billing/statements/:id
API->>Store: fetch statement groups (timestamp, items[])
Store-->>API: BillingStatementGroup[]
API-->>Dev: BillingStatementResource { groups: BillingStatementGroup[] }
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
# Conflicts: # packages/types/src/commerce.ts # packages/types/src/json.ts
@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: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/types/src/commerce.ts (1)
702-728: Enforce mutual exclusivity and required fields in ConfirmCheckoutParams
gatewayis documented as required withpaymentToken/useTestCard, but the types don’t enforce it. Also ensure only one strategy is allowed.-export type ConfirmCheckoutParams = - | { - /** - * The ID of a saved payment source to use for this checkout. - */ - paymentSourceId?: string; - } - | { - /** - * A token representing payment details, usually from a payment form. **Requires** `gateway` to be provided. - */ - paymentToken?: string; - /** - * The payment gateway to use. **Required** if `paymentToken` or `useTestCard` is provided. - */ - gateway?: PaymentGateway; - } - | { - /** - * The payment gateway to use. **Required** if `paymentToken` or `useTestCard` is provided. - */ - gateway?: PaymentGateway; - /** - * If true, uses a test card for the checkout. **Requires** `gateway` to be provided. - */ - useTestCard?: boolean; - }; +export type ConfirmCheckoutParams = + | { + /** The ID of a saved payment source to use for this checkout. */ + paymentSourceId: string; + paymentToken?: never; + useTestCard?: never; + gateway?: never; + } + | { + /** A token representing payment details, usually from a payment form. */ + paymentToken: string; + /** Required with `paymentToken`. */ + gateway: PaymentGateway; + paymentSourceId?: never; + useTestCard?: never; + } + | { + /** If true, uses a test card for the checkout. */ + useTestCard: true; + /** Required with `useTestCard`. */ + gateway: PaymentGateway; + paymentSourceId?: never; + paymentToken?: never; + };
🧹 Nitpick comments (4)
packages/types/src/jwtv2.ts (1)
91-91: Typo in tuple label: fistFactorAge → firstFactorAgeFix the label to avoid leaking a typo in public docs.
- fva?: [fistFactorAge: number, secondFactorAge: number]; + fva?: [firstFactorAge: number, secondFactorAge: number];.typedoc/custom-theme.mjs (1)
292-317: Make “Type declaration” removal more robustCurrent regex only matches exactly “## Type declaration”. Consider handling different heading levels/spacing and collapsing leftover blank lines.
- const filteredOutput = output.replace(/^## Type declaration$/gm, ''); - - return filteredOutput; + const filteredOutput = output + // Remove any 'Type declaration' heading regardless of heading level/spacing/case + .replace(/^\s*#{2,}\s*Type declaration\s*$/gmi, '') + // Collapse excessive blank lines that may remain after removal + .replace(/\n{3,}/g, '\n\n') + .trimEnd(); + return filteredOutput;packages/types/src/commerce.ts (2)
781-784: Doc/type mismatch for freeTrialEndsAtType is
Date | null, but doc says “Unix timestamp (milliseconds)”. Align the doc with the type.- /** - * Unix timestamp (milliseconds) of when the free trial ends. - */ + /** + * The date and time when the free trial ends. + */ freeTrialEndsAt: Date | null;
344-346: Undocumented field: paymentMethodOrderAvoid lingering TODOs in public types. Briefly describe expected values/semantics or hide until documented.
Do you want me to propose wording based on the current API behavior?
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (9)
.typedoc/custom-plugin.mjs(0 hunks).typedoc/custom-theme.mjs(3 hunks)packages/backend/src/api/resources/CommercePlan.ts(1 hunks)packages/types/src/clerk.ts(2 hunks)packages/types/src/commerce.ts(14 hunks)packages/types/src/deletedObject.ts(1 hunks)packages/types/src/json.ts(1 hunks)packages/types/src/jwtv2.ts(1 hunks)packages/types/src/pagination.ts(1 hunks)
💤 Files with no reviewable changes (1)
- .typedoc/custom-plugin.mjs
🧰 Additional context used
📓 Path-based instructions (6)
**/*.{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/CommercePlan.tspackages/types/src/jwtv2.tspackages/types/src/pagination.tspackages/types/src/deletedObject.tspackages/types/src/clerk.tspackages/types/src/json.tspackages/types/src/commerce.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/CommercePlan.tspackages/types/src/jwtv2.tspackages/types/src/pagination.tspackages/types/src/deletedObject.tspackages/types/src/clerk.tspackages/types/src/json.tspackages/types/src/commerce.ts
packages/**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
TypeScript is required for all packages
Files:
packages/backend/src/api/resources/CommercePlan.tspackages/types/src/jwtv2.tspackages/types/src/pagination.tspackages/types/src/deletedObject.tspackages/types/src/clerk.tspackages/types/src/json.tspackages/types/src/commerce.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/CommercePlan.tspackages/types/src/jwtv2.tspackages/types/src/pagination.tspackages/types/src/deletedObject.tspackages/types/src/clerk.tspackages/types/src/json.tspackages/types/src/commerce.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/CommercePlan.tspackages/types/src/jwtv2.tspackages/types/src/pagination.tspackages/types/src/deletedObject.tspackages/types/src/clerk.tspackages/types/src/json.tspackages/types/src/commerce.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/CommercePlan.tspackages/types/src/jwtv2.tspackages/types/src/pagination.tspackages/types/src/deletedObject.tspackages/types/src/clerk.tspackages/types/src/json.tspackages/types/src/commerce.ts
🧬 Code graph analysis (1)
packages/types/src/commerce.ts (2)
packages/types/src/resource.ts (1)
ClerkResource(8-21)packages/types/src/deletedObject.ts (1)
DeletedObjectResource(4-21)
⏰ 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: Analyze (javascript-typescript)
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: semgrep-cloud-platform/scan
🔇 Additional comments (8)
packages/backend/src/api/resources/CommercePlan.ts (1)
7-10: Docs: verify link targets render correctly after Typedoc changesConfirm the slug
/docs/references/javascript/types/billing-plan-resourceand the Backend API link resolve as expected in the built docs. The theme/plugin changes could affect these paths.packages/types/src/pagination.ts (1)
3-3: LGTM: adds @interface for Typedoc stylingConsistent with ClerkPaginationParams usage.
packages/types/src/jwtv2.ts (1)
88-90: LGTM: experimental note formattingNo semantic changes.
packages/types/src/json.ts (1)
148-150: LGTM: experimental note formattingMatches jwtv2.ts.
packages/types/src/clerk.ts (2)
1578-1583: LGTM: doc style consistency for __experimental_asStandalone (UserButtonProps)No API change.
1648-1654: LGTM: doc style consistency for __experimental_asStandalone (OrganizationSwitcherProps)No API change.
packages/types/src/deletedObject.ts (1)
1-21: LGTM: JSDoc added for DeletedObjectResourceClear, concise field docs.
packages/types/src/commerce.ts (1)
813-816: Clarify userId field descriptionThe description repeats “payer ID” but the field is
userId.
[raise_nitpick_refactor]- /** - * The unique identifier for the payer. - */ + /** + * The user ID associated with this payer. + */ userId?: string;
packages/types/src/commerce.ts
Outdated
| name: string; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * The price of the plan for a single billing period (usually monthly). For example, `1000` for $10.00. |
There was a problem hiding this comment.
fee always represents monthly.
BillingMoneyAmount is an object, so I think the example is a bit off. I'd simply skip it.
packages/types/src/commerce.ts
Outdated
| fee: BillingMoneyAmount; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * The total price for a full year of the plan, in the smallest unit of the currency. For example, `10000` for $100.00. |
packages/types/src/commerce.ts
Outdated
| annualFee: BillingMoneyAmount; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * The effective monthly price when billed annually, in the smallest unit of the currency. For example, `833` for $8.33. |
packages/types/src/commerce.ts
Outdated
| externalGatewayId: string; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * TODO(@COMMERCE): document this |
There was a problem hiding this comment.
It is the order the payment methods will be displayed when <PaymentElement/> renders.
packages/types/src/commerce.ts
Outdated
| amount?: BillingMoneyAmount; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * The credit info for the subscription item, if any. |
There was a problem hiding this comment.
It's the credit amount from a previous purchase.
packages/types/src/commerce.ts
Outdated
|
|
||
| /** | ||
| * Whether the payer is eligible for a free trial. | ||
| * Whether the subscription is eligible for a free trial. |
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/types/src/commerce.ts (1)
695-729: ConfirmCheckoutParams allows {} and multiple fields — enforce exactly-one and required gateway where needed.Make the union exclusive and require gateway with paymentToken/useTestCard to prevent invalid states.
Apply this diff:
-export type ConfirmCheckoutParams = - | { - /** - * The ID of a saved payment source to use for this checkout. - */ - paymentSourceId?: string; - } - | { - /** - * A token representing payment details, usually from a payment form. **Requires** `gateway` to be provided. - */ - paymentToken?: string; - /** - * The payment gateway to use. **Required** if `paymentToken` or `useTestCard` is provided. - */ - gateway?: PaymentGateway; - } - | { - /** - * The payment gateway to use. **Required** if `paymentToken` or `useTestCard` is provided. - */ - gateway?: PaymentGateway; - /** - * If true, uses a test card for the checkout. **Requires** `gateway` to be provided. - */ - useTestCard?: boolean; - }; +export type ConfirmCheckoutParams = + | { + /** The ID of a saved payment source to use for this checkout. */ + paymentSourceId: string; + paymentToken?: never; + gateway?: never; + useTestCard?: never; + } + | { + /** A token representing payment details, usually from a payment form. */ + paymentToken: string; + /** Required when `paymentToken` is provided. */ + gateway: PaymentGateway; + paymentSourceId?: never; + useTestCard?: never; + } + | { + /** Uses a test card for the checkout. */ + useTestCard: true; + /** Required when `useTestCard` is provided. */ + gateway: PaymentGateway; + paymentSourceId?: never; + paymentToken?: never; + };
♻️ Duplicate comments (1)
packages/types/src/commerce.ts (1)
679-682: Doc-method mismatch resolved — looks good.The comment now correctly refers to startCheckout(). Matches the exported API.
🧹 Nitpick comments (7)
packages/types/src/commerce.ts (7)
781-784: freeTrialEndsAt doc/type mismatch.Doc says “Unix timestamp (ms)” but type is Date | null. Align the doc.
Apply this diff:
- /** - * Unix timestamp (milliseconds) of when the free trial ends. - */ + /** + * The date when the free trial ends. + */ freeTrialEndsAt: Date | null;
320-328: Prefer Promise over Promise for makeDefault, and update the doc.This matches TS conventions and avoids null checks.
Apply this diff:
- /** - * @param params - The parameters for the make default operation. - * @returns A promise that resolves to `null`. - */ - makeDefault: (params?: MakeDefaultPaymentSourceParams) => Promise<null>; + /** + * @param params - The parameters for the make default operation. + * @returns A promise that resolves when the operation completes. + */ + makeDefault: (params?: MakeDefaultPaymentSourceParams) => Promise<void>;
160-164: Terminology consistency: use “payer type” (not “subscriber type”).Docs elsewhere standardize on “payer”.
Apply this diff:
- /** - * Specifies the subscriber type this plan is designed for. - * - * Each plan is exclusively created for either individual users or organizations, and cannot be used interchangeably. - */ + /** + * Specifies the payer type this plan is designed for. + * + * Each plan is exclusively created for either individual users or organizations, and cannot be used interchangeably. + */
369-372: Make id readonly (matches ClerkResource and intent).Child resources should not relax readonly. Strengthen to readonly for consistency.
Apply this diff:
- id: string; + readonly id: string;
431-434: Make statement id readonly for consistency.Apply this diff:
- id: string; + readonly id: string;
458-467: Consider readonly for group items to reflect immutability.Prevents accidental mutation in consumers.
Apply this diff:
- items: BillingPaymentResource[]; + readonly items: readonly BillingPaymentResource[];
791-836: Fix inaccurate JSDoc on userId.The text repeats “identifier for the payer”; clarify it refers to the User.
Apply this diff:
- /** - * The unique identifier for the payer. - */ + /** + * The user ID of the payer (if the payer is a user). + */ userId?: string;
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
packages/types/src/commerce.ts(13 hunks)
🧰 Additional context used
📓 Path-based instructions (6)
**/*.{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/types/src/commerce.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/types/src/commerce.ts
packages/**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
TypeScript is required for all packages
Files:
packages/types/src/commerce.ts
packages/**/*.{ts,tsx,d.ts}
📄 CodeRabbit inference engine (.cursor/rules/development.mdc)
Packages should export TypeScript types alongside runtime code
Files:
packages/types/src/commerce.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/types/src/commerce.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/types/src/commerce.ts
🧬 Code graph analysis (1)
packages/types/src/commerce.ts (2)
packages/types/src/resource.ts (1)
ClerkResource(8-21)packages/types/src/deletedObject.ts (1)
DeletedObjectResource(4-21)
⏰ 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). (3)
- GitHub Check: Analyze (javascript-typescript)
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: semgrep-cloud-platform/scan
🔇 Additional comments (3)
packages/types/src/commerce.ts (3)
344-346: Correct and clear wording for paymentMethodOrder.Matches prior feedback: it’s the display order in .
334-346: Initialized payment source docs read well.Good alignment with UI semantics and gateway fields.
678-683: No publiccreateCheckoutusages found — only internal factories/types remain.Search found only internal symbols (createCheckoutManager, createCheckoutInstance, createCheckoutPageObject) and the type CreateCheckoutParams (packages/types/src/commerce.ts) — no stale docs or public API call named
createCheckoutremain.
| /** | ||
| * The unique identifier for the subscription item. | ||
| */ | ||
| id: string; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * The unique identifier for the payment source being used for the subscription item. | ||
| */ | ||
| //TODO(@COMMERCE): should this be nullable ? | ||
| paymentSourceId: string; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * The plan associated with the subscription item. | ||
| */ | ||
| plan: BillingPlanResource; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * The billing period for the subscription item. | ||
| */ | ||
| planPeriod: BillingSubscriptionPlanPeriod; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * The status of the subscription item. | ||
| */ | ||
| status: BillingSubscriptionStatus; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * The date and time when the subscription item was created. | ||
| */ | ||
| createdAt: Date; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * The date and time when the subscription item became past due. `null` if the subscription item is not past due. | ||
| */ | ||
| pastDueAt: Date | null; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * The date and time when the current billing period starts. | ||
| */ | ||
| periodStart: Date; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * The date and time when the current billing period ends. `null` if not set. | ||
| */ | ||
| periodEnd: Date | null; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * The date and time when the subscription item was canceled. `null` if the subscription item is not canceled. | ||
| */ | ||
| canceledAt: Date | null; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * The amount charged for the subscription item. | ||
| */ | ||
| amount?: BillingMoneyAmount; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * The credit from a previous purchase that is being applied to the subscription item. | ||
| */ | ||
| credit?: { | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * The amount of credit from a previous purchase that is being applied to the subscription item. | ||
| */ | ||
| amount: BillingMoneyAmount; | ||
| }; | ||
| /** | ||
| * @experimental This is an experimental API for the Billing feature that is available under a public beta, and the API is subject to change. It is advised to [pin](https://clerk.com/docs/pinning) the SDK version and the clerk-js version to avoid breaking changes. | ||
| * A function to cancel the subscription item. Accepts the following parameters: | ||
| * <ul> | ||
| * <li>`orgId?` (`string`): The ID of the organization to cancel the subscription item from.</li> | ||
| * </ul> | ||
| * | ||
| * @param params - The parameters for the cancel operation. | ||
| * @returns A promise that resolves to a `DeletedObjectResource` object. | ||
| */ | ||
| cancel: (params: CancelSubscriptionParams) => Promise<DeletedObjectResource>; | ||
| /** |
There was a problem hiding this comment.
🛠️ Refactor suggestion
🧩 Analysis chain
cancel params should be optional (consistency + ergonomics) and TODO needs resolution.
- Other methods (remove/makeDefault) accept optional params; align cancel for parity.
- Resolve TODO on paymentSourceId nullability and reflect the decision in types/JSDoc.
Apply this diff:
- //TODO(@COMMERCE): should this be nullable ?
- paymentSourceId: string;
+ // NOTE: If a plan can exist without a payment source, make this `string | null`.
+ paymentSourceId: string;
@@
- cancel: (params: CancelSubscriptionParams) => Promise<DeletedObjectResource>;
+ cancel: (params?: CancelSubscriptionParams) => Promise<DeletedObjectResource>;To verify usages and avoid breaks, run:
🏁 Script executed:
#!/bin/bash
rg -n -C2 '\bcancel\(' --type ts --type tsxLength of output: 27
🏁 Script executed:
#!/bin/bash
# Search for all `cancel()` invocations across TypeScript files
rg -n -C2 'cancel\s*\(' -g '*.ts' -g '*.tsx'Length of output: 1477
🏁 Script executed:
#!/bin/bash
set -euo pipefail
FILE="packages/clerk-js/src/core/resources/CommerceSubscription.ts"
echo "== File exists: $FILE =="
if [ -f "$FILE" ]; then
echo "yes"
else
echo "no"; exit 0
fi
echo
echo "== CommerceSubscription.ts (lines 1-240) =="
nl -ba "$FILE" | sed -n '1,240p'
echo
echo "== Search repo for CancelSubscriptionParams =="
rg -n "CancelSubscriptionParams" || true
echo
echo "== Search repo for makeDefault method definitions =="
rg -n "makeDefault\s*\(" || true
echo
echo "== Search repo for remove method definitions (word-boundary) =="
rg -n "\bremove\s*\(" || true
echo
echo "== Search repo for other 'cancel' method declarations =="
rg -n "public\s+async\s+cancel" || true
echo
echo "== Search for .cancel( usages across the repo (ts/tsx/js/jsx) =="
rg -n -S "\.cancel\s*\(" || trueLength of output: 170
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== packages/types/src/commerce.ts (lines 460-560) =="
sed -n '460,560p' packages/types/src/commerce.ts || true
echo
echo "== Show lines in types file that mention paymentSourceId or cancel =="
rg -n "paymentSourceId|cancel\s*:" packages/types/src/commerce.ts || true
echo
echo "== Locate CancelSubscriptionParams definition =="
rg -n "CancelSubscriptionParams" || true
echo
echo "== packages/clerk-js/src/core/resources/CommerceSubscription.ts (full file) =="
sed -n '1,400p' packages/clerk-js/src/core/resources/CommerceSubscription.ts || true
echo
echo "== packages/clerk-js/src/ui/components/SubscriptionDetails/index.tsx (lines 180-210) =="
sed -n '180,210p' packages/clerk-js/src/ui/components/SubscriptionDetails/index.tsx || true
echo
echo "== All .cancel( usages across repo (ts/tsx/js/jsx) =="
rg -n -S "\.cancel\s*\(" --hidden --glob '!**/node_modules/**' || trueLength of output: 9872
Make cancel params optional and resolve paymentSourceId nullability — update types AND implementation
- Change types: packages/types/src/commerce.ts — make BillingSubscriptionItemResource.cancel accept an optional param: cancel(params?: CancelSubscriptionParams) => Promise.
- Update implementation: packages/clerk-js/src/core/resources/CommerceSubscription.ts — change method to public async cancel(params?: CancelSubscriptionParams) and guard the destructure (e.g. const { orgId } = params ?? {}).
- Resolve TODO: decide if paymentSourceId can be null. If nullable, change packages/types/src/commerce.ts paymentSourceId: string -> string | null and update clerk-js BillingSubscriptionItem (property type and fromJSON assignment: this.paymentSourceId = data.payment_source_id ?? null).
- Repo check: .cancel(...) callers found only in packages/clerk-js/src/ui/components/SubscriptionDetails/index.tsx (callsite already passes an object); update JSDoc/comments to reflect the chosen nullability and optional param.
Description
🚨 related to Replace "commerce" with "billing"; use typedoc for billing type references clerk-docs#2605 (pull this PR with this clerk-docs PR to preview how they're rendered in clerk-docs)
Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change
Summary by CodeRabbit
New Features
Documentation