Skip to content

Conversation

panteliselef
Copy link
Member

@panteliselef panteliselef commented Sep 19, 2025

Description

Updating public apis to include Billing instead of Commerce.

Checklist

  • pnpm test runs as expected.
  • pnpm build runs as expected.
  • (If applicable) JSDoc comments have been added or updated for any package exports
  • (If applicable) Documentation has been updated

Type of change

  • 🐛 Bug fix
  • 🌟 New feature
  • 🔨 Breaking change
  • 📖 Refactoring / dependency upgrade / documentation
  • other:

Summary by CodeRabbit

  • New Features

    • Added new subscription item webhook events: canceled, upcoming, ended, and abandoned.
  • Refactor

    • Renamed public API surface from Commerce* to Billing* across resources, JSON types, endpoints, and webhooks.
    • Standardized resource fields to camelCase (e.g., payerId, createdAt, pastDueAt, nextPayment) for subscriptions and subscription items.
    • Updated return types and exports to use Billing* names consistently.
    • No runtime behavior changes; update integrations to new names.
    • Included a changeset marking a minor release.

@panteliselef panteliselef self-assigned this Sep 19, 2025
Copy link

changeset-bot bot commented Sep 19, 2025

🦋 Changeset detected

Latest commit: cff948f

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 11 packages
Name Type
@clerk/backend Minor
@clerk/agent-toolkit Patch
@clerk/astro Patch
@clerk/express Patch
@clerk/fastify Patch
@clerk/nextjs Patch
@clerk/nuxt Patch
@clerk/react-router Patch
@clerk/remix Patch
@clerk/tanstack-react-start Patch
@clerk/testing Patch

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

Copy link

vercel bot commented Sep 19, 2025

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Preview Comments Updated (UTC)
clerk-js-sandbox Ready Ready Preview Comment Sep 19, 2025 8:29am

Copy link
Contributor

coderabbitai bot commented Sep 19, 2025

Walkthrough

Renames “Commerce” types, classes, enums, and exports to “Billing” across backend resources, API endpoints, JSON schemas, webhooks, deserializer, and public index. Adds new subscription item webhook event variants. Updates field names to camelCase in resource classes. Includes a changeset marking a minor update for @clerk/backend.

Changes

Cohort / File(s) Summary of changes
Changeset metadata
\.changeset/tricky-moments-film.md
Adds changeset describing Commerce→Billing rename for backend billing domain; no code changes.
Billing API endpoint types
packages/backend/src/api/endpoints/BillingApi.ts
Replaces Commerce* types with Billing* types in method signatures and return types; no logic changes.
Resource: Plan
packages/backend/src/api/resources/CommercePlan.ts
Renames class CommercePlan→BillingPlan; updates JSON type CommercePlanJSON→BillingPlanJSON; adjusts fromJSON signatures/returns.
Resource: Subscription
packages/backend/src/api/resources/CommerceSubscription.ts
Renames CommerceSubscription→BillingSubscription; switches snake_case fields to camelCase; updates nextPayment type; updates fromJSON and imports to Billing*.
Resource: SubscriptionItem
packages/backend/src/api/resources/CommerceSubscriptionItem.ts
Renames CommerceSubscriptionItem→BillingSubscriptionItem; converts constructor fields to camelCase; plan type to BillingPlan; updates fromJSON and typings.
Deserializer mappings
packages/backend/src/api/resources/Deserializer.ts
Updates imports and switch cases from Commerce* to Billing* (Plan, Subscription, SubscriptionItem).
JSON schemas and enums
packages/backend/src/api/resources/JSON.ts
Renames Commerce* JSON interfaces/enums to Billing* while preserving discriminator string values; aligns nested money/totals types; updates webhook payload JSON types.
Webhooks
packages/backend/src/api/resources/Webhooks.ts
Renames exported webhook event types to Billing*; expands SubscriptionItem event variants to include canceled, upcoming, ended, abandoned.
Public exports
packages/backend/src/index.ts
Re-exports Billing* JSON/resource/webhook types in place of Commerce*; no runtime changes.

Sequence Diagram(s)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

Suggested labels

backend

Suggested reviewers

  • mauricioabreu
  • wobsoriano
  • aeliox

Poem

I thump my paws—rename delight!
Commerce to Billing, tidy and bright.
Webhooks hop with events anew,
CamelCase fields, a fresher view.
In burrows of types, I neatly align—
Version bumps nibble, code looks fine. 🐇✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)
Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. You can run @coderabbitai generate docstrings to improve docstring coverage.
✅ Passed checks (2 passed)
Check name Status Explanation
Title Check ✅ Passed The title "chore(backend): Rename commerce resources to billing resources" accurately and concisely summarizes the main change in the PR by describing the backend-wide rename of Commerce* resources to Billing* and follows conventional commit style, making intent and scope clear to reviewers. It is specific, related to the changeset, and sufficiently descriptive for a quick scan of commit history.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
✨ Finishing touches
  • 📝 Generate Docstrings
🧪 Generate unit tests
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch elef/bill-1249-backend

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link

pkg-pr-new bot commented Sep 19, 2025

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@6812

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@6812

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@6812

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@6812

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@6812

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@6812

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@6812

@clerk/clerk-expo

npm i https://pkg.pr.new/@clerk/clerk-expo@6812

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@6812

@clerk/express

npm i https://pkg.pr.new/@clerk/express@6812

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@6812

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@6812

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@6812

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@6812

@clerk/clerk-react

npm i https://pkg.pr.new/@clerk/clerk-react@6812

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@6812

@clerk/remix

npm i https://pkg.pr.new/@clerk/remix@6812

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@6812

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@6812

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@6812

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@6812

@clerk/types

npm i https://pkg.pr.new/@clerk/types@6812

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@6812

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@6812

commit: cff948f

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)
packages/backend/src/api/resources/JSON.ts (1)

984-999: Fix nullable subscription_items mismatch (runtime crash risk)

packages/types/src/json.ts declares subscription_items: BillingSubscriptionItemJSON[] | null (line ~781) but packages/backend/src/api/resources/JSON.ts declares it non-nullable (line ~992). CommerceSubscription.fromJSON maps without a null guard — if the API returns null this will throw.

  • Broaden the backend type to match the nullable server shape:
-  subscription_items: BillingSubscriptionItemJSON[];
+  subscription_items: BillingSubscriptionItemJSON[] | null;
  • Harden the deserializer in packages/backend/src/api/resources/CommerceSubscription.ts:
-      data.subscription_items.map(item => BillingSubscriptionItem.fromJSON(item)),
+      (data.subscription_items ?? []).map(item => BillingSubscriptionItem.fromJSON(item)),
packages/backend/src/api/endpoints/BillingApi.ts (1)

39-44: Fix base path inconsistency and add explicit return type

Endpoints mix '/commerce' and '/billing'. Set basePath to '/billing' and add explicit return types per guidelines.

Apply:

-const basePath = '/commerce';
+const basePath = '/billing';
@@
-type GetOrganizationListParams = ClerkPaginationRequest<{
+type GetPlanListParams = ClerkPaginationRequest<{
   payerType: 'org' | 'user';
 }>;
@@
-  public async getPlanList(params?: GetOrganizationListParams) {
-    return this.request<PaginatedResourceResponse<BillingPlan[]>>({
+  public async getPlanList(
+    params?: GetPlanListParams,
+  ): Promise<PaginatedResourceResponse<BillingPlan[]>> {
+    return this.request<PaginatedResourceResponse<BillingPlan[]>>({
       method: 'GET',
-      path: joinPaths(basePath, 'plans'),
+      path: joinPaths(basePath, 'plans'),
       queryParams: params,
     });
   }
🧹 Nitpick comments (19)
packages/backend/src/api/resources/CommerceSubscriptionItem.ts (2)

6-10: Docs links still point to “commerce” slugs—please verify/update.

The JSDoc references “commerce-subscription-item-resource” and “/tag/commerce/.../subscription_items”. If the public docs moved to “billing” slugs with this rename, update the URLs and display names accordingly. If the backend docs intentionally keep “commerce_*” paths, add a short note to avoid confusion.


45-46: Tighten amount typing to match JSON shape.

Local JSON typings define amount: BillingMoneyAmountJSON | null (not undefined). Consider removing undefined from the public field:

-    readonly amount: BillingMoneyAmount | null | undefined,
+    readonly amount: BillingMoneyAmount | null,

If any upstream can truly omit amount, keep undefined but please document it here.

packages/backend/src/api/resources/JSON.ts (4)

68-72: Rename surfaced as “Billing” but discriminators remain “commerce_*” — add an inline comment.*

This is correct for wire compatibility, but it’s easy to misread. Add a comment explaining that object discriminator values intentionally remain commerce_* while the SDK types/classes are renamed to Billing.

   Permission: 'permission',
-  BillingPayer: 'commerce_payer',
+  // Note: Discriminator values intentionally remain `commerce_*` for wire compatibility.
+  BillingPayer: 'commerce_payer',

802-815: Duplicate BillingMoneyAmountJSON type sources—risk of drift.

This file declares its own BillingMoneyAmountJSON, while other modules import the same-named type from @clerk/types. Prefer a single source of truth (import and re-export, or rename the local alias) to avoid subtle mismatches.

- interface BillingMoneyAmountJSON {
+ // Consider importing from @clerk/types and re-exporting, or rename this to BackendBillingMoneyAmountJSON.
+ interface BackendBillingMoneyAmountJSON {

Follow through the few references in this file if you adopt the rename.

Also applies to: 816-821


864-885: Inconsistent next_payment.amount typing vs subscription.next_payment.

Here next_payment.amount is number, while BillingSubscriptionJSON.next_payment.amount is BillingMoneyAmountJSON. If intentional, please add a doc note; otherwise, align both to the same money shape.


887-928: Webhook event shapes: verify proration_date and lifetime_paid types.

  • proration_date: string — server usually sends epoch numbers; confirm this isn’t a timestamp.
  • lifetime_paid: number here, but BillingSubscriptionItemJSON.lifetime_paid is a money object. If this is a deliberate webhook-specific simplification, document it in the interface TSDoc.
.changeset/tricky-moments-film.md (1)

5-5: Add migration notes and clarify release impact.

This rename alters exported class/type names in @clerk/backend (e.g., CommercePlanBillingPlan). Unless you maintain deprecated re-exports, that’s a breaking surface for consumers. Either:

  • Mark as major, or
  • Keep deprecated re-exports for one cycle and note removal timing.

Also add a short “How to migrate” block with before/after imports for Plan/Subscription/Item and a note that discriminators remain commerce_*.

packages/backend/src/api/resources/CommercePlan.ts (3)

6-10: Docs links still reference “/tag/commerce/.../plans”.

If the docs have moved to “billing” slugs, update URLs. If they intentionally remain under “commerce”, add a clarifying note in JSDoc.


71-96: Shared money-amount formatter is duplicated across resources.

formatAmountJSON appears in multiple files. Extract a tiny util (e.g., formatBillingMoneyAmountJSON) and reuse to reduce drift.

-  static fromJSON(data: BillingPlanJSON): BillingPlan {
-    const formatAmountJSON = (fee: BillingPlanJSON['fee']) => {
-      return { ... };
-    };
+  static fromJSON(data: BillingPlanJSON): BillingPlan {
+    // use a shared helper: formatBillingMoneyAmountJSON(fee)

Happy to provide a small PR-ready helper if you want it bundled here.


1-4: Class/file naming mismatch (CommercePlan.ts exports BillingPlan).

It works, but the path is surprising. Consider renaming the file to BillingPlan.ts (with a re-export shim if needed) to match the class and new naming scheme.

Also applies to: 11-11

packages/backend/src/api/resources/Deserializer.ts (1)

40-42: Imports point to ./Commerce* files exporting Billing*.

It’s fine functionally. For consistency, consider renaming files to Billing* and updating import paths.

packages/backend/src/api/endpoints/BillingApi.ts (5)

51-56: Add explicit return type

Return type should be Promise.

Apply:

-  public async cancelSubscriptionItem(subscriptionItemId: string, params?: CancelSubscriptionItemParams) {
+  public async cancelSubscriptionItem(
+    subscriptionItemId: string,
+    params?: CancelSubscriptionItemParams,
+  ): Promise<BillingSubscriptionItem> {
     this.requireId(subscriptionItemId);
     return this.request<BillingSubscriptionItem>({
       method: 'DELETE',
-      path: joinPaths(basePath, 'subscription_items', subscriptionItemId),
+      path: joinPaths(basePath, 'subscription_items', subscriptionItemId),
       queryParams: params,
     });
   }

66-71: Use basePath instead of hard-coded '/billing' and add explicit return type

Keep path building consistent and typed.

Apply:

-  public async extendSubscriptionItemFreeTrial(
+  public async extendSubscriptionItemFreeTrial(
     subscriptionItemId: string,
     params: ExtendSubscriptionItemFreeTrialParams,
-  ) {
+  ): Promise<BillingSubscriptionItem> {
     this.requireId(subscriptionItemId);
     return this.request<BillingSubscriptionItem>({
       method: 'POST',
-      path: joinPaths('/billing', 'subscription_items', subscriptionItemId, 'extend_free_trial'),
+      path: joinPaths(basePath, 'subscription_items', subscriptionItemId, 'extend_free_trial'),
       bodyParams: params,
     });
   }

78-82: Add explicit return type

Per guidelines, public APIs should declare return types.

Apply:

-  public async getOrganizationBillingSubscription(organizationId: string) {
+  public async getOrganizationBillingSubscription(organizationId: string): Promise<BillingSubscription> {
     this.requireId(organizationId);
     return this.request<BillingSubscription>({
       method: 'GET',
       path: joinPaths(organizationBasePath, organizationId, 'billing', 'subscription'),
     });
   }

89-93: Add explicit return type

Same as above for user endpoint.

Apply:

-  public async getUserBillingSubscription(userId: string) {
+  public async getUserBillingSubscription(userId: string): Promise<BillingSubscription> {
     this.requireId(userId);
     return this.request<BillingSubscription>({
       method: 'GET',
       path: joinPaths(userBasePath, userId, 'billing', 'subscription'),
     });
   }

4-6: Align resource filenames with exported class names (Commerce → Billing)**

packages/backend/src/api/resources/CommercePlan.ts, CommerceSubscription.ts and CommerceSubscriptionItem.ts export classes named BillingPlan/BillingSubscription/BillingSubscriptionItem while packages/backend/src/api/endpoints/BillingApi.ts imports the Commerce* files — rename the files to Billing* or add small re-export shims (e.g., BillingPlan.ts exporting { BillingPlan } from './CommercePlan') or add Billing* exports to resources/index.ts to remove the cognitive mismatch.

packages/backend/src/api/resources/CommerceSubscription.ts (2)

3-4: Import path name mismatch (Commerce vs Billing)

Class names are Billing*, but file path is Commerce*. Consider renaming files/paths to Billing* or adding re-exports to reduce cognitive load.


76-76: Null-safety on subscription_items if upstream ever returns null

Local BillingSubscriptionJSON enforces an array, but other packages show it can be null. If this type is ever widened, guard accordingly.

Apply defensively (only if JSON type changes):

-      data.subscription_items.map(item => BillingSubscriptionItem.fromJSON(item)),
+      (data.subscription_items ?? []).map(item => BillingSubscriptionItem.fromJSON(item)),
packages/backend/src/api/resources/Webhooks.ts (1)

68-76: PaymentAttempt event alias rename is fine; add brief JSDoc for public API

Public type aliases benefit from a one-liner JSDoc.

📜 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.

📥 Commits

Reviewing files that changed from the base of the PR and between 99922ec and cff948f.

⛔ Files ignored due to path filters (1)
  • .typedoc/__tests__/__snapshots__/file-structure.test.ts.snap is excluded by !**/*.snap
📒 Files selected for processing (9)
  • .changeset/tricky-moments-film.md (1 hunks)
  • packages/backend/src/api/endpoints/BillingApi.ts (6 hunks)
  • packages/backend/src/api/resources/CommercePlan.ts (2 hunks)
  • packages/backend/src/api/resources/CommerceSubscription.ts (4 hunks)
  • packages/backend/src/api/resources/CommerceSubscriptionItem.ts (5 hunks)
  • packages/backend/src/api/resources/Deserializer.ts (2 hunks)
  • packages/backend/src/api/resources/JSON.ts (12 hunks)
  • packages/backend/src/api/resources/Webhooks.ts (4 hunks)
  • packages/backend/src/index.ts (3 hunks)
🧰 Additional context used
📓 Path-based instructions (9)
.changeset/**

📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)

Automated releases must use Changesets.

Files:

  • .changeset/tricky-moments-film.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/resources/Webhooks.ts
  • packages/backend/src/api/resources/CommercePlan.ts
  • packages/backend/src/api/resources/Deserializer.ts
  • packages/backend/src/api/endpoints/BillingApi.ts
  • packages/backend/src/index.ts
  • packages/backend/src/api/resources/JSON.ts
  • packages/backend/src/api/resources/CommerceSubscriptionItem.ts
  • packages/backend/src/api/resources/CommerceSubscription.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/Webhooks.ts
  • packages/backend/src/api/resources/CommercePlan.ts
  • packages/backend/src/api/resources/Deserializer.ts
  • packages/backend/src/api/endpoints/BillingApi.ts
  • packages/backend/src/index.ts
  • packages/backend/src/api/resources/JSON.ts
  • packages/backend/src/api/resources/CommerceSubscriptionItem.ts
  • packages/backend/src/api/resources/CommerceSubscription.ts
packages/**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

TypeScript is required for all packages

Files:

  • packages/backend/src/api/resources/Webhooks.ts
  • packages/backend/src/api/resources/CommercePlan.ts
  • packages/backend/src/api/resources/Deserializer.ts
  • packages/backend/src/api/endpoints/BillingApi.ts
  • packages/backend/src/index.ts
  • packages/backend/src/api/resources/JSON.ts
  • packages/backend/src/api/resources/CommerceSubscriptionItem.ts
  • packages/backend/src/api/resources/CommerceSubscription.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/Webhooks.ts
  • packages/backend/src/api/resources/CommercePlan.ts
  • packages/backend/src/api/resources/Deserializer.ts
  • packages/backend/src/api/endpoints/BillingApi.ts
  • packages/backend/src/index.ts
  • packages/backend/src/api/resources/JSON.ts
  • packages/backend/src/api/resources/CommerceSubscriptionItem.ts
  • packages/backend/src/api/resources/CommerceSubscription.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
Avoid any type - prefer unknown when type is uncertain, then narrow with type guards
Use interface for object shapes that might be extended
Use type for unions, primitives, and computed types
Prefer readonly properties for immutable data structures
Use private for internal implementation details
Use protected for inheritance hierarchies
Use public explicitly for clarity in public APIs
Prefer readonly for 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
Use const assertions for literal types: as const
Use satisfies operator 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 ...
No any types without justification
Proper error handling with typed errors
Consistent use of readonly for 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/Webhooks.ts
  • packages/backend/src/api/resources/CommercePlan.ts
  • packages/backend/src/api/resources/Deserializer.ts
  • packages/backend/src/api/endpoints/BillingApi.ts
  • packages/backend/src/index.ts
  • packages/backend/src/api/resources/JSON.ts
  • packages/backend/src/api/resources/CommerceSubscriptionItem.ts
  • packages/backend/src/api/resources/CommerceSubscription.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/Webhooks.ts
  • packages/backend/src/api/resources/CommercePlan.ts
  • packages/backend/src/api/resources/Deserializer.ts
  • packages/backend/src/api/endpoints/BillingApi.ts
  • packages/backend/src/index.ts
  • packages/backend/src/api/resources/JSON.ts
  • packages/backend/src/api/resources/CommerceSubscriptionItem.ts
  • packages/backend/src/api/resources/CommerceSubscription.ts
packages/**/index.{js,ts}

📄 CodeRabbit inference engine (.cursor/rules/development.mdc)

Use tree-shaking friendly exports

Files:

  • packages/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/index.ts
🧬 Code graph analysis (7)
packages/backend/src/api/resources/Webhooks.ts (2)
packages/backend/src/index.ts (3)
  • BillingPaymentAttemptWebhookEvent (170-170)
  • BillingSubscriptionWebhookEvent (171-171)
  • BillingSubscriptionItemWebhookEvent (172-172)
packages/backend/src/api/resources/JSON.ts (3)
  • BillingPaymentAttemptWebhookEventJSON (932-963)
  • BillingSubscriptionWebhookEventJSON (968-982)
  • BillingSubscriptionItemWebhookEventJSON (890-927)
packages/backend/src/api/resources/CommercePlan.ts (3)
packages/clerk-js/src/core/resources/CommercePlan.ts (1)
  • BillingPlan (7-54)
packages/backend/src/api/resources/JSON.ts (1)
  • BillingPlanJSON (833-849)
packages/types/src/json.ts (1)
  • BillingPlanJSON (643-669)
packages/backend/src/api/resources/Deserializer.ts (5)
packages/backend/src/api/resources/JSON.ts (2)
  • ObjectType (19-74)
  • ObjectType (76-76)
packages/backend/src/api/resources/CommercePlan.ts (1)
  • BillingPlan (11-97)
packages/backend/src/index.ts (3)
  • BillingPlan (148-148)
  • BillingSubscription (149-149)
  • BillingSubscriptionItem (150-150)
packages/backend/src/api/resources/CommerceSubscription.ts (1)
  • BillingSubscription (11-81)
packages/backend/src/api/resources/CommerceSubscriptionItem.ts (1)
  • BillingSubscriptionItem (11-128)
packages/backend/src/api/endpoints/BillingApi.ts (4)
packages/backend/src/api/resources/Deserializer.ts (1)
  • PaginatedResourceResponse (66-71)
packages/backend/src/api/resources/CommercePlan.ts (1)
  • BillingPlan (11-97)
packages/backend/src/api/resources/CommerceSubscriptionItem.ts (1)
  • BillingSubscriptionItem (11-128)
packages/backend/src/api/resources/CommerceSubscription.ts (1)
  • BillingSubscription (11-81)
packages/backend/src/api/resources/JSON.ts (1)
packages/types/src/json.ts (7)
  • BillingPayerJSON (836-852)
  • ClerkResourceJSON (46-50)
  • BillingMoneyAmountJSON (788-793)
  • BillingPlanJSON (643-669)
  • FeatureJSON (631-638)
  • BillingSubscriptionItemJSON (737-758)
  • BillingSubscriptionJSON (763-783)
packages/backend/src/api/resources/CommerceSubscriptionItem.ts (3)
packages/backend/src/index.ts (3)
  • BillingSubscriptionItem (150-150)
  • BillingSubscriptionItemJSON (105-105)
  • BillingPlan (148-148)
packages/backend/src/api/resources/JSON.ts (1)
  • BillingSubscriptionItemJSON (864-885)
packages/backend/src/api/resources/CommercePlan.ts (1)
  • BillingPlan (11-97)
packages/backend/src/api/resources/CommerceSubscription.ts (4)
packages/clerk-js/src/core/resources/CommerceSubscription.ts (2)
  • BillingSubscription (18-58)
  • BillingSubscriptionItem (60-122)
packages/backend/src/api/resources/JSON.ts (1)
  • BillingSubscriptionJSON (984-998)
packages/types/src/json.ts (1)
  • BillingSubscriptionJSON (763-783)
packages/backend/src/api/resources/CommerceSubscriptionItem.ts (1)
  • BillingSubscriptionItem (11-128)
⏰ 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-cloud-platform/scan
  • GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (9)
packages/backend/src/api/resources/CommerceSubscriptionItem.ts (1)

108-126: LGTM: fromJSON field mapping looks consistent (camelCase ↔ snake_case).

Status, planPeriod, nextPayment, amounts, plan, and timestamp fields are all mapped correctly.

packages/backend/src/api/resources/Deserializer.ts (1)

186-191: LGTM — Deserializer adds Billing discriminators; verify remaining Commerce filenames.*

Deserializer returns BillingPlan, BillingSubscription, and BillingSubscriptionItem correctly.

Remaining Commerce* references (confirm intent / whether they should be renamed):

  • packages/backend/src/api/endpoints/BillingApi.ts:4-6
  • packages/backend/src/api/resources/index.ts:60-62
  • packages/backend/src/api/resources/CommerceSubscription.ts:3
  • packages/backend/src/api/resources/CommerceSubscriptionItem.ts:3
  • packages/backend/src/api/resources/Deserializer.ts:40-42
  • packages/clerk-js/src/core/resources/internal.ts:12-13
packages/backend/src/index.ts (3)

148-151: Resources export rename is consistent

Exports align with the new Billing* resources. No issues spotted.


170-173: Webhook type exports updated — confirm docs include new subscriptionItem variants

rg returned no matches for subscriptionItem.(canceled|upcoming|ended|abandoned) in packages; confirm documentation/webhook docs list the new BillingSubscriptionItemWebhookEvent variants: canceled, upcoming, ended, abandoned. Location: packages/backend/src/index.ts (lines 170–173).


103-106: Billing JSON exports look good — add deprecated Commerce aliases in @clerk/backend**

Repo search found no tracked source files importing CommercePlanJSON, CommerceSubscriptionJSON, or CommerceSubscriptionItemJSON (occurrences limited to CHANGELOGs and types, e.g. packages/clerk-js/CHANGELOG.md and packages/types/**). Add temporary deprecated re-exports in @clerk/backend mapping:

  • CommercePlanJSON → BillingPlanJSON
  • CommerceSubscriptionJSON → BillingSubscriptionJSON
  • CommerceSubscriptionItemJSON → BillingSubscriptionItemJSON
    to avoid breaking external consumers.
packages/backend/src/api/resources/Webhooks.ts (3)

2-4: Renamed JSON payload imports align with Billing

Imports are correct and scoped. No issues.


104-106: WebhookEvent union updated correctly

Union now includes Billing* variants; looks good.


78-90: New subscription item webhook variants added — confirm backend emits these exact event names and update docs

Ensure the backend emits: subscriptionItem.created, subscriptionItem.updated, subscriptionItem.active, subscriptionItem.canceled, subscriptionItem.upcoming, subscriptionItem.ended, subscriptionItem.abandoned, subscriptionItem.incomplete, subscriptionItem.pastDue, subscriptionItem.freeTrialEnding; and update API docs/consumer mappings. File: packages/backend/src/api/resources/Webhooks.ts (lines 78–90). rg search produced no matches in the repo — manual verification required.

packages/backend/src/api/resources/CommerceSubscription.ts (1)

7-11: No change needed — JS docs slug is correct
The JavaScript SDK types page uses /docs/references/javascript/types/commerce-subscription-resource; the Backend docs use a different slug (commerce-subscription). Keep the existing link.

@panteliselef panteliselef merged commit 1ad3b92 into main Sep 19, 2025
43 checks passed
@panteliselef panteliselef deleted the elef/bill-1249-backend branch September 19, 2025 15:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants