feat(clerk-js, localizations, ui): Add credits information in the user/org profile#8977
Merged
dstaley merged 20 commits intoJun 30, 2026
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
🦋 Changeset detectedLatest commit: 2878666 The changes in this PR will be included in the next version bump. This PR includes changesets to release 23 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 |
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe PR adds billing credit balance and history APIs, shared types/resources/hooks, UI sections and routes, localization entries, release metadata, and a bundlewatch config update. ChangesBilling credits
Sequence Diagram(s)Included above in the hidden review stack artifact. Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Comment |
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/electron
@clerk/electron-passkeys
@clerk/eslint-plugin
@clerk/expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/hono
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/react
@clerk/react-router
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/ui
@clerk/upgrade
@clerk/vue
commit: |
l-armstrong
changed the title
l-armstrong
force-pushed
the
lamone/bill-1613-add-credits-information-in-the-userorg-profile
branch
from
f51ea07 to
68ba47e
Compare
l-armstrong
changed the title
Contributor
API Changes Report
Summary
@clerk/sharedCurrent version: 4.22.1 Subpath
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (5)
packages/clerk-js/src/core/resources/BillingCreditLedger.ts (1)
7-35: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value
extends BaseResourceappears unnecessary here.
BillingCreditLedgerextendsBaseResourcebut uses none of its capabilities (no_fetch,withDefault, etc.), while the siblingBillingCreditBalanceis a plain class. For consistency and to avoid pulling inBaseResourceplumbing, consider making this a plain class implementingBillingCreditLedgerResource. If the inheritance is intentional (e.g., a future need forBaseResourcehelpers), disregard.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/clerk-js/src/core/resources/BillingCreditLedger.ts` around lines 7 - 35, BillingCreditLedger is inheriting BaseResource without using any BaseResource behavior, so simplify it for consistency with BillingCreditBalance. Update the BillingCreditLedger class to be a plain class that still implements BillingCreditLedgerResource, and keep the existing constructor/fromJSON data-mapping logic intact. If there is no current or planned use of BaseResource helpers in BillingCreditLedger, remove the inheritance so the class is self-contained.packages/shared/src/types/billing.ts (3)
960-969: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueAdd the
@experimentalJSDoc block toGetCreditBalanceParams.
GetCreditHistoryParams(Line 974) carries the@experimentalnotice, butGetCreditBalanceParamsdoes not. Keep them consistent since both are reference-facing.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/shared/src/types/billing.ts` around lines 960 - 969, Add the missing `@experimental` JSDoc block to GetCreditBalanceParams so it matches GetCreditHistoryParams and stays consistent with the other reference-facing billing types. Update the GetCreditBalanceParams type definition in billing.ts to include the same experimental notice alongside its existing property docs, without changing the shape of the type.Source: Path instructions
985-996: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winDocument
BillingCreditLedgerResourceproperties.Unlike
BillingSubscriptionResourceandBillingCreditBalanceResource, the ledger properties (amount,currency,sourceType,sourceId, etc.) have no JSDoc. These render in the generated Clerk reference docs, so per-property descriptions help avoid customer-facing docs drift; the Docs team may want to review. Also consider documenting thatamount/currencyare raw values here rather than aBillingMoneyAmountlike the balance resource, since that asymmetry is easy to misuse downstream (e.g. formatting in the history page).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/shared/src/types/billing.ts` around lines 985 - 996, Document the fields on BillingCreditLedgerResource with per-property JSDoc so the generated Clerk reference docs have clear descriptions for id, payerId, amount, currency, sourceType, sourceId, and createdAt. Use the BillingSubscriptionResource and BillingCreditBalanceResource typings as the style reference, and add a note near amount/currency that these are raw values here rather than a BillingMoneyAmount to avoid misuse in downstream formatting. Keep the comments aligned with the BillingCreditLedgerResource interface so the Docs team can review the updated public API wording.Source: Path instructions
86-98: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd
@returnsto the new method JSDoc for docs consistency.Every other
BillingNamespacemethod documents its return shape with@returns(seegetStatements,getPlan, etc.), which the generated Clerk reference docs render.getCreditBalanceandgetCreditHistoryomit it. Since these are reference-facing APIs, the Docs team may need to review.📝 Proposed JSDoc
/** * Gets the credit balance for the current payer. * + * `@returns` A [`BillingCreditBalanceResource`](/docs/reference/types/billing-credit-balance-resource) object. + * * `@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. */ getCreditBalance: (params: GetCreditBalanceParams) => Promise<BillingCreditBalanceResource>; /** * Gets the credit history for the current payer. * + * `@returns` A [`ClerkPaginatedResponse`](/docs/reference/types/clerk-paginated-response) of [`BillingCreditLedgerResource`](/docs/reference/types/billing-credit-ledger-resource) objects. + * * `@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. */ getCreditHistory: (params: GetCreditHistoryParams) => Promise<ClerkPaginatedResponse<BillingCreditLedgerResource>>;🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/shared/src/types/billing.ts` around lines 86 - 98, Add `@returns` JSDoc entries to the BillingNamespace methods getCreditBalance and getCreditHistory in billing.ts so they match the rest of the namespace docs. Keep the existing experimental notes, and document the return shapes for BillingCreditBalanceResource and ClerkPaginatedResponse<BillingCreditLedgerResource> in the same JSDoc blocks so the generated reference docs include them consistently.Sources: Coding guidelines, Path instructions
packages/ui/src/contexts/components/Plans.tsx (1)
98-114: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueAdd explicit return types to the new exported hooks.
useCreditBalanceanduseCreditHistoryare exported but lack explicit return types. Annotating them with the underlying result types (e.g.CreditBalanceResult/ the credit-history query result) keeps the public surface self-documenting and stable.As per coding guidelines: "Always define explicit return types for functions, especially public APIs".
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/ui/src/contexts/components/Plans.tsx` around lines 98 - 114, Add explicit return type annotations to the exported hooks in Plans.tsx. `useCreditBalance` and `useCreditHistory` are public APIs, so update their signatures to return the appropriate underlying result types instead of relying on inference. Use the existing symbols `useCreditBalance`, `useCreditHistory`, `__experimental_useCreditBalance`, and `__internal_useCreditHistoryQuery` to match the hook result types already returned.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/clerk-js/src/core/resources/BillingSubscription.ts`:
- Line 39: The BillingSubscription model currently declares payerId as non-null
even though it is assigned from backend data.payer_id in the resource
initializer, so it can be undefined at runtime if the response omits that field.
Update the payerId typing and assignment in BillingSubscription (including the
related parsing/serialization path around the class constructor or load method)
to reflect the actual API contract: either make payerId optional or provide a
safe default, and ensure any downstream accessors or consumers that rely on
payerId handle the missing case correctly.
In `@packages/ui/src/components/AccountCredits/CreditHistoryPage.tsx`:
- Line 23: Add an explicit return type to the exported CreditHistoryPage
component so its signature is unambiguous; update the CreditHistoryPage function
declaration itself to return JSX.Element (or the project’s equivalent React
component return type) rather than relying on inference.
---
Nitpick comments:
In `@packages/clerk-js/src/core/resources/BillingCreditLedger.ts`:
- Around line 7-35: BillingCreditLedger is inheriting BaseResource without using
any BaseResource behavior, so simplify it for consistency with
BillingCreditBalance. Update the BillingCreditLedger class to be a plain class
that still implements BillingCreditLedgerResource, and keep the existing
constructor/fromJSON data-mapping logic intact. If there is no current or
planned use of BaseResource helpers in BillingCreditLedger, remove the
inheritance so the class is self-contained.
In `@packages/shared/src/types/billing.ts`:
- Around line 960-969: Add the missing `@experimental` JSDoc block to
GetCreditBalanceParams so it matches GetCreditHistoryParams and stays consistent
with the other reference-facing billing types. Update the GetCreditBalanceParams
type definition in billing.ts to include the same experimental notice alongside
its existing property docs, without changing the shape of the type.
- Around line 985-996: Document the fields on BillingCreditLedgerResource with
per-property JSDoc so the generated Clerk reference docs have clear descriptions
for id, payerId, amount, currency, sourceType, sourceId, and createdAt. Use the
BillingSubscriptionResource and BillingCreditBalanceResource typings as the
style reference, and add a note near amount/currency that these are raw values
here rather than a BillingMoneyAmount to avoid misuse in downstream formatting.
Keep the comments aligned with the BillingCreditLedgerResource interface so the
Docs team can review the updated public API wording.
- Around line 86-98: Add `@returns` JSDoc entries to the BillingNamespace methods
getCreditBalance and getCreditHistory in billing.ts so they match the rest of
the namespace docs. Keep the existing experimental notes, and document the
return shapes for BillingCreditBalanceResource and
ClerkPaginatedResponse<BillingCreditLedgerResource> in the same JSDoc blocks so
the generated reference docs include them consistently.
In `@packages/ui/src/contexts/components/Plans.tsx`:
- Around line 98-114: Add explicit return type annotations to the exported hooks
in Plans.tsx. `useCreditBalance` and `useCreditHistory` are public APIs, so
update their signatures to return the appropriate underlying result types
instead of relying on inference. Use the existing symbols `useCreditBalance`,
`useCreditHistory`, `__experimental_useCreditBalance`, and
`__internal_useCreditHistoryQuery` to match the hook result types already
returned.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: 2e63fbf1-9fc8-4594-b074-906d797443be
📒 Files selected for processing (23)
packages/clerk-js/bundlewatch.config.jsonpackages/clerk-js/src/core/modules/billing/namespace.tspackages/clerk-js/src/core/resources/BillingCreditBalance.tspackages/clerk-js/src/core/resources/BillingCreditLedger.tspackages/clerk-js/src/core/resources/BillingSubscription.tspackages/clerk-js/src/core/resources/internal.tspackages/localizations/src/en-US.tspackages/shared/src/react/hooks/index.tspackages/shared/src/react/hooks/useCreditBalance.tsxpackages/shared/src/react/hooks/useCreditHistory.tsxpackages/shared/src/react/stable-keys.tspackages/shared/src/types/billing.tspackages/shared/src/types/elementIds.tspackages/shared/src/types/json.tspackages/shared/src/types/localization.tspackages/ui/src/components/AccountCredits/AccountCredits.tsxpackages/ui/src/components/AccountCredits/CreditHistoryPage.tsxpackages/ui/src/components/AccountCredits/index.tspackages/ui/src/components/OrganizationProfile/OrganizationBillingPage.tsxpackages/ui/src/components/OrganizationProfile/OrganizationProfileRoutes.tsxpackages/ui/src/components/UserProfile/BillingPage.tsxpackages/ui/src/components/UserProfile/UserProfileRoutes.tsxpackages/ui/src/contexts/components/Plans.tsx
Display the C2's remaining payer credit in the OrganizationProfile component.
l-armstrong
force-pushed
the
lamone/bill-1613-add-credits-information-in-the-userorg-profile
branch
from
d6d25f0 to
4902172
Compare
dstaley
approved these changes
Jun 30, 2026
Comment on lines
+35
to
+39
| <ProfileSection.Button | ||
| id='accountCredits' | ||
| localizationKey={localizationKeys(`${localizationRoot}.billingPage.accountCreditsSection.viewHistory`)} | ||
| sx={[t => ({ justifyContent: 'start', height: t.sizes.$8 })]} | ||
| onClick={() => void navigate('credit-history')} |
Member
There was a problem hiding this comment.
I think this is fine for now, but we should iterate on it because we now have three different types of buttons on the same page:
- Icon, label, no arrow
- Icon, label, arrow on hover
- No icon, label, no arrow on hover
Would be nice to have some consistent logic being used here for when a button needs an icon, and when it should show an arrow.
Contributor
Author
There was a problem hiding this comment.
Makes sense. I made a ticket for it to track this https://linear.app/clerk/issue/BILL-1845/improve-ui-consistency-for-account-credits-component
dstaley
approved these changes
Jun 30, 2026
dstaley
deleted the
lamone/bill-1613-add-credits-information-in-the-userorg-profile
branch
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
3 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.
Display the C2's remaining account credit and their account credit history in the user/org profile.
Description
Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change
Summary by CodeRabbit
Summary by CodeRabbit