chore(backend): Rename commerce resources to billing resources (#6812)

Author: panteliselef

.changeset/tricky-moments-film.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+[Billing Beta] Rename types and classes that contain commerce to use billing instead.

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -235,15 +235,15 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "backend/allowlist-identifier.mdx",
   "backend/auth-object.mdx",
   "backend/authenticate-request-options.mdx",
+  "backend/billing-payment-attempt-webhook-event-json.mdx",
+  "backend/billing-plan-json.mdx",
+  "backend/billing-plan.mdx",
+  "backend/billing-subscription-item-json.mdx",
+  "backend/billing-subscription-item-webhook-event-json.mdx",
+  "backend/billing-subscription-item.mdx",
+  "backend/billing-subscription-webhook-event-json.mdx",
+  "backend/billing-subscription.mdx",
   "backend/client.mdx",
-  "backend/commerce-payment-attempt-webhook-event-json.mdx",
-  "backend/commerce-plan-json.mdx",
-  "backend/commerce-plan.mdx",
-  "backend/commerce-subscription-item-json.mdx",
-  "backend/commerce-subscription-item-webhook-event-json.mdx",
-  "backend/commerce-subscription-item.mdx",
-  "backend/commerce-subscription-webhook-event-json.mdx",
-  "backend/commerce-subscription.mdx",
   "backend/email-address.mdx",
   "backend/external-account.mdx",
   "backend/feature.mdx",

packages/backend/src/api/endpoints/BillingApi.ts

@@ -1,9 +1,9 @@
 import type { ClerkPaginationRequest } from '@clerk/types';
 
 import { joinPaths } from '../../util/path';
-import type { CommercePlan } from '../resources/CommercePlan';
-import type { CommerceSubscription } from '../resources/CommerceSubscription';
-import type { CommerceSubscriptionItem } from '../resources/CommerceSubscriptionItem';
+import type { BillingPlan } from '../resources/CommercePlan';
+import type { BillingSubscription } from '../resources/CommerceSubscription';
+import type { BillingSubscriptionItem } from '../resources/CommerceSubscriptionItem';
 import type { PaginatedResourceResponse } from '../resources/Deserializer';
 import { AbstractAPI } from './AbstractApi';
 
@@ -36,7 +36,7 @@ export class BillingAPI extends AbstractAPI {
    * @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.
    */
   public async getPlanList(params?: GetOrganizationListParams) {
-    return this.request<PaginatedResourceResponse<CommercePlan[]>>({
+    return this.request<PaginatedResourceResponse<BillingPlan[]>>({
       method: 'GET',
       path: joinPaths(basePath, 'plans'),
       queryParams: params,
@@ -48,7 +48,7 @@ export class BillingAPI extends AbstractAPI {
    */
   public async cancelSubscriptionItem(subscriptionItemId: string, params?: CancelSubscriptionItemParams) {
     this.requireId(subscriptionItemId);
-    return this.request<CommerceSubscriptionItem>({
+    return this.request<BillingSubscriptionItem>({
       method: 'DELETE',
       path: joinPaths(basePath, 'subscription_items', subscriptionItemId),
       queryParams: params,
@@ -63,7 +63,7 @@ export class BillingAPI extends AbstractAPI {
     params: ExtendSubscriptionItemFreeTrialParams,
   ) {
     this.requireId(subscriptionItemId);
-    return this.request<CommerceSubscriptionItem>({
+    return this.request<BillingSubscriptionItem>({
       method: 'POST',
       path: joinPaths('/billing', 'subscription_items', subscriptionItemId, 'extend_free_trial'),
       bodyParams: params,
@@ -75,7 +75,7 @@ export class BillingAPI extends AbstractAPI {
    */
   public async getOrganizationBillingSubscription(organizationId: string) {
     this.requireId(organizationId);
-    return this.request<CommerceSubscription>({
+    return this.request<BillingSubscription>({
       method: 'GET',
       path: joinPaths(organizationBasePath, organizationId, 'billing', 'subscription'),
     });
@@ -86,7 +86,7 @@ export class BillingAPI extends AbstractAPI {
    */
   public async getUserBillingSubscription(userId: string) {
     this.requireId(userId);
-    return this.request<CommerceSubscription>({
+    return this.request<BillingSubscription>({
       method: 'GET',
       path: joinPaths(userBasePath, userId, 'billing', 'subscription'),
     });

packages/backend/src/api/resources/CommercePlan.ts

@@ -1,14 +1,14 @@
 import type { BillingMoneyAmount } from '@clerk/types';
 
 import { Feature } from './Feature';
-import type { CommercePlanJSON } from './JSON';
+import type { BillingPlanJSON } from './JSON';
 
 /**
- * The `CommercePlan` object is similar to the [`BillingPlanResource`](/docs/references/javascript/types/billing-plan-resource) object as it holds information about a plan, as well as methods for managing it. However, the `CommercePlan` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/plans) and is not directly accessible from the Frontend API.
+ * The `BillingPlan` object is similar to the [`BillingPlanResource`](/docs/references/javascript/types/billing-plan-resource) object as it holds information about a plan, as well as methods for managing it. However, the `BillingPlan` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/plans) and is not directly accessible from the Frontend API.
  *
  * @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.
  */
-export class CommercePlan {
+export class BillingPlan {
   constructor(
     /**
      * The unique identifier for the plan.
@@ -68,16 +68,16 @@ export class CommercePlan {
     readonly features: Feature[],
   ) {}
 
-  static fromJSON(data: CommercePlanJSON): CommercePlan {
-    const formatAmountJSON = (fee: CommercePlanJSON['fee']) => {
+  static fromJSON(data: BillingPlanJSON): BillingPlan {
+    const formatAmountJSON = (fee: BillingPlanJSON['fee']) => {
       return {
         amount: fee.amount,
         amountFormatted: fee.amount_formatted,
         currency: fee.currency,
         currencySymbol: fee.currency_symbol,
       };
     };
-    return new CommercePlan(
+    return new BillingPlan(
       data.id,
       data.product_id,
       data.name,

packages/backend/src/api/resources/CommerceSubscription.ts

@@ -1,23 +1,23 @@
-import { type BillingMoneyAmount } from '@clerk/types';
+import type { BillingMoneyAmount } from '@clerk/types';
 
-import { CommerceSubscriptionItem } from './CommerceSubscriptionItem';
-import type { CommerceSubscriptionJSON } from './JSON';
+import { BillingSubscriptionItem } from './CommerceSubscriptionItem';
+import type { BillingSubscriptionJSON } from './JSON';
 
 /**
- * The `CommerceSubscription` object is similar to the [`CommerceSubscriptionResource`](/docs/references/javascript/types/commerce-subscription-resource) object as it holds information about a subscription, as well as methods for managing it. However, the `CommerceSubscription` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/get/organizations/%7Borganization_id%7D/billing/subscription) and is not directly accessible from the Frontend API.
+ * The `BillingSubscription` object is similar to the [`BillingSubscriptionResource`](/docs/references/javascript/types/commerce-subscription-resource) object as it holds information about a subscription, as well as methods for managing it. However, the `BillingSubscription` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/billing/get/organizations/%7Borganization_id%7D/billing/subscription) and is not directly accessible from the Frontend API.
  *
  * @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.
  */
-export class CommerceSubscription {
+export class BillingSubscription {
   constructor(
     /**
-     * The unique identifier for the commerce subscription.
+     * The unique identifier for the billing subscription.
      */
     readonly id: string,
     /**
      * The current status of the subscription.
      */
-    readonly status: CommerceSubscriptionJSON['status'],
+    readonly status: BillingSubscriptionJSON['status'],
     /**
      * The ID of the payer for this subscription.
      */
@@ -41,7 +41,7 @@ export class CommerceSubscription {
     /**
      * Array of subscription items in this subscription.
      */
-    readonly subscriptionItems: CommerceSubscriptionItem[],
+    readonly subscriptionItems: BillingSubscriptionItem[],
     /**
      * Information about the next scheduled payment.
      */
@@ -52,7 +52,7 @@ export class CommerceSubscription {
     readonly eligibleForFreeTrial: boolean,
   ) {}
 
-  static fromJSON(data: CommerceSubscriptionJSON): CommerceSubscription {
+  static fromJSON(data: BillingSubscriptionJSON): BillingSubscription {
     const nextPayment = data.next_payment
       ? {
           date: data.next_payment.date,
@@ -65,15 +65,15 @@ export class CommerceSubscription {
         }
       : null;
 
-    return new CommerceSubscription(
+    return new BillingSubscription(
       data.id,
       data.status,
       data.payer_id,
       data.created_at,
       data.updated_at,
       data.active_at ?? null,
       data.past_due_at ?? null,
-      data.subscription_items.map(item => CommerceSubscriptionItem.fromJSON(item)),
+      data.subscription_items.map(item => BillingSubscriptionItem.fromJSON(item)),
       nextPayment,
       data.eligible_for_free_trial ?? false,
     );

packages/backend/src/api/resources/CommerceSubscriptionItem.ts

@@ -1,14 +1,14 @@
 import type { BillingMoneyAmount, BillingMoneyAmountJSON } from '@clerk/types';
 
-import { CommercePlan } from './CommercePlan';
-import type { CommerceSubscriptionItemJSON } from './JSON';
+import { BillingPlan } from './CommercePlan';
+import type { BillingSubscriptionItemJSON } from './JSON';
 
 /**
- * The `CommerceSubscriptionItem` object is similar to the [`CommerceSubscriptionItemResource`](/docs/references/javascript/types/commerce-subscription-item-resource) object as it holds information about a subscription item, as well as methods for managing it. However, the `CommerceSubscriptionItem` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/subscription_items) and is not directly accessible from the Frontend API.
+ * The `BillingSubscriptionItem` object is similar to the [`BillingSubscriptionItemResource`](/docs/references/javascript/types/commerce-subscription-item-resource) object as it holds information about a subscription item, as well as methods for managing it. However, the `BillingSubscriptionItem` object is different in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/commerce/get/commerce/subscription_items) and is not directly accessible from the Frontend API.
  *
  * @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.
  */
-export class CommerceSubscriptionItem {
+export class BillingSubscriptionItem {
   constructor(
     /**
      * The unique identifier for the subscription item.
@@ -17,7 +17,7 @@ export class CommerceSubscriptionItem {
     /**
      * The status of the subscription item.
      */
-    readonly status: CommerceSubscriptionItemJSON['status'],
+    readonly status: BillingSubscriptionItemJSON['status'],
     /**
      * The plan period for the subscription item.
      */
@@ -46,7 +46,7 @@ export class CommerceSubscriptionItem {
     /**
      * The plan associated with this subscription item.
      */
-    readonly plan: CommercePlan,
+    readonly plan: BillingPlan,
     /**
      * The plan ID.
      */
@@ -89,7 +89,7 @@ export class CommerceSubscriptionItem {
     readonly lifetimePaid?: BillingMoneyAmount | null,
   ) {}
 
-  static fromJSON(data: CommerceSubscriptionItemJSON): CommerceSubscriptionItem {
+  static fromJSON(data: BillingSubscriptionItemJSON): BillingSubscriptionItem {
     function formatAmountJSON(
       amount: BillingMoneyAmountJSON | null | undefined,
     ): BillingMoneyAmount | null | undefined {
@@ -105,14 +105,14 @@ export class CommerceSubscriptionItem {
       };
     }
 
-    return new CommerceSubscriptionItem(
+    return new BillingSubscriptionItem(
       data.id,
       data.status,
       data.plan_period,
       data.period_start,
       data.next_payment,
       formatAmountJSON(data.amount),
-      CommercePlan.fromJSON(data.plan),
+      BillingPlan.fromJSON(data.plan),
       data.plan_id,
       data.created_at,
       data.updated_at,

packages/backend/src/api/resources/Deserializer.ts

@@ -37,9 +37,9 @@ import {
   User,
 } from '.';
 import { AccountlessApplication } from './AccountlessApplication';
-import { CommercePlan } from './CommercePlan';
-import { CommerceSubscription } from './CommerceSubscription';
-import { CommerceSubscriptionItem } from './CommerceSubscriptionItem';
+import { BillingPlan } from './CommercePlan';
+import { BillingSubscription } from './CommerceSubscription';
+import { BillingSubscriptionItem } from './CommerceSubscriptionItem';
 import { Feature } from './Feature';
 import type { PaginatedResponseJSON } from './JSON';
 import { ObjectType } from './JSON';
@@ -183,12 +183,12 @@ function jsonToObject(item: any): any {
       return User.fromJSON(item);
     case ObjectType.WaitlistEntry:
       return WaitlistEntry.fromJSON(item);
-    case ObjectType.CommercePlan:
-      return CommercePlan.fromJSON(item);
-    case ObjectType.CommerceSubscription:
-      return CommerceSubscription.fromJSON(item);
-    case ObjectType.CommerceSubscriptionItem:
-      return CommerceSubscriptionItem.fromJSON(item);
+    case ObjectType.BillingPlan:
+      return BillingPlan.fromJSON(item);
+    case ObjectType.BillingSubscription:
+      return BillingSubscription.fromJSON(item);
+    case ObjectType.BillingSubscriptionItem:
+      return BillingSubscriptionItem.fromJSON(item);
     case ObjectType.Feature:
       return Feature.fromJSON(item);
     default: