chore(backend,types): Update JSDoc comments & export Feature type (#6649)

Author: alexisintech

.changeset/three-knives-play.md

@@ -0,0 +1,7 @@
+---
+'@clerk/backend': patch
+'@clerk/types': patch
+---
+
+- Export `Feature` type from backend resource.
+- Re-export canonical `CommerceMoneyAmount` type from `@clerk/types`.

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

@@ -232,6 +232,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "backend/commerce-subscription.mdx",
   "backend/email-address.mdx",
   "backend/external-account.mdx",
+  "backend/feature.mdx",
   "backend/get-auth-fn.mdx",
   "backend/identification-link.mdx",
   "backend/infer-auth-object-from-token-array.mdx",

.typedoc/custom-plugin.mjs

@@ -55,6 +55,7 @@ const LINK_REPLACEMENTS = [
   ['verify-token-options', '#verify-token-options'],
   ['localization-resource', '/docs/customization/localization'],
   ['commerce-subscription-item-resource', '/docs/references/javascript/types/commerce-subscription-item-resource'],
+  ['commerce-money-amount', '/docs/references/javascript/types/commerce-money-amount'],
 ];
 
 /**

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

@@ -1,16 +1,12 @@
+import type { CommerceMoneyAmount } from '@clerk/types';
+
 import { Feature } from './Feature';
 import type { CommercePlanJSON } from './JSON';
 
-export type CommerceMoneyAmount = {
-  amount: number;
-  amountFormatted: string;
-  currency: string;
-  currencySymbol: 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 the SDK version to avoid breaking changes.
+ * The `CommercePlan` object is similar to the [`CommercePlanResource`](/docs/references/javascript/types/commerce-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){{ target: '_blank' }} 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 the SDK version to avoid breaking changes.
  */
 export class CommercePlan {
   constructor(
@@ -19,7 +15,7 @@ export class CommercePlan {
      */
     readonly id: string,
     /**
-     * The id of the product the plan belongs to.
+     * The ID of the product the plan belongs to.
      */
     readonly productId: string,
     /**

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

@@ -1,10 +1,12 @@
-import { type CommerceMoneyAmount } from './CommercePlan';
+import { type CommerceMoneyAmount } from '@clerk/types';
+
 import { CommerceSubscriptionItem } from './CommerceSubscriptionItem';
 import type { CommerceSubscriptionJSON } from './JSON';
 
 /**
- * @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 the SDK version to avoid breaking changes.
+ * 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){{ target: '_blank' }} 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 the SDK version to avoid breaking changes.
  */
 export class CommerceSubscription {
   constructor(
@@ -21,19 +23,19 @@ export class CommerceSubscription {
      */
     readonly payerId: string,
     /**
-     * Unix timestamp (milliseconds) of creation.
+     * Unix timestamp (milliseconds) of when the subscription was created.
      */
     readonly createdAt: number,
     /**
-     * Unix timestamp (milliseconds) of last update.
+     * Unix timestamp (milliseconds) of when the subscription was last updated.
      */
     readonly updatedAt: number,
     /**
-     * Unix timestamp (milliseconds) when the subscription became active.
+     * Unix timestamp (milliseconds) of when the subscription became active.
      */
     readonly activeAt: number | null,
     /**
-     * Unix timestamp (milliseconds) when the subscription became past due.
+     * Unix timestamp (milliseconds) of when the subscription became past due.
      */
     readonly pastDueAt: number | null,
     /**

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

@@ -1,11 +1,12 @@
-import type { CommerceMoneyAmountJSON } from '@clerk/types';
+import type { CommerceMoneyAmount, CommerceMoneyAmountJSON } from '@clerk/types';
 
-import { type CommerceMoneyAmount, CommercePlan } from './CommercePlan';
+import { CommercePlan } from './CommercePlan';
 import type { CommerceSubscriptionItemJSON } from './JSON';
 
 /**
- * @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 the SDK version to avoid breaking changes.
+ * 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){{ target: '_blank' }} 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 the SDK version to avoid breaking changes.
  */
 export class CommerceSubscriptionItem {
   constructor(
@@ -22,14 +23,20 @@ export class CommerceSubscriptionItem {
      */
     readonly planPeriod: 'month' | 'annual',
     /**
-     * The start of the current period.
+     * Unix timestamp (milliseconds) of when the current period starts.
      */
     readonly periodStart: number,
     /**
      * The next payment information.
      */
     readonly nextPayment: {
+      /**
+       * The amount of the next payment.
+       */
       amount: number;
+      /**
+       * Unix timestamp (milliseconds) of when the next payment is scheduled.
+       */
       date: number;
     } | null,
     /**
@@ -45,27 +52,27 @@ export class CommerceSubscriptionItem {
      */
     readonly planId: string,
     /**
-     * The date and time the subscription item was created.
+     * Unix timestamp (milliseconds) of when the subscription item was created.
      */
     readonly createdAt: number,
     /**
-     * The date and time the subscription item was last updated.
+     * Unix timestamp (milliseconds) of when the subscription item was last updated.
      */
     readonly updatedAt: number,
     /**
-     * The end of the current period.
+     * Unix timestamp (milliseconds) of when the current period ends.
      */
     readonly periodEnd: number | null,
     /**
-     * When the subscription item was canceled.
+     * Unix timestamp (milliseconds) of when the subscription item was canceled.
      */
     readonly canceledAt: number | null,
     /**
-     * When the subscription item became past due.
+     * Unix timestamp (milliseconds) of when the subscription item became past due.
      */
     readonly pastDueAt: number | null,
     /**
-     * When the subscription item ended.
+     * Unix timestamp (milliseconds) of when the subscription item ended.
      */
     readonly endedAt: number | null,
     /**

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

@@ -1,11 +1,31 @@
 import type { FeatureJSON } from './JSON';
 
+/**
+ * The `Feature` object represents a feature of a subscription plan.
+ *
+ * @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 the SDK version to avoid breaking changes.
+ */
 export class Feature {
   constructor(
+    /**
+     * The unique identifier for the feature.
+     */
     readonly id: string,
+    /**
+     * The name of the feature.
+     */
     readonly name: string,
+    /**
+     * The description of the feature.
+     */
     readonly description: string,
+    /**
+     * The URL-friendly identifier of the feature.
+     */
     readonly slug: string,
+    /**
+     * The URL of the feature's avatar image.
+     */
     readonly avatarUrl: string,
   ) {}
 

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

@@ -60,6 +60,7 @@ export * from './Web3Wallet';
 export * from './CommercePlan';
 export * from './CommerceSubscription';
 export * from './CommerceSubscriptionItem';
+export * from './Feature';
 
 export type {
   EmailWebhookEvent,

packages/backend/src/index.ts

@@ -119,6 +119,7 @@ export type {
   Domain,
   EmailAddress,
   ExternalAccount,
+  Feature,
   Instance,
   InstanceRestrictions,
   InstanceSettings,