chore(clerk-js,shared): Expose experimental useSubscription

.changeset/rare-readers-cough.md

@@ -0,0 +1,9 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/types': minor
+---
+
+[Billing Beta] Introduce top level subscription.
+
+Updated `CommerceSubscriptionJSON` to describe the top level subscription and renamed the existing type to `CommerceSubscriptionItemJSON`.
+Deprecated `billing.getSubscriptions()` in favour of `billing.getSubscription`. 

.changeset/wide-loops-decide.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+[Billing Beta] Replace `useSubscriptionItems` with `useSubscription`.

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

@@ -52,6 +52,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/commerce-statement-status.mdx",
   "types/commerce-statement-totals-json.mdx",
   "types/commerce-statement-totals.mdx",
+  "types/commerce-subscription-item-json.mdx",
+  "types/commerce-subscription-item-resource.mdx",
   "types/commerce-subscription-json.mdx",
   "types/commerce-subscription-plan-period.mdx",
   "types/commerce-subscription-resource.mdx",
@@ -65,6 +67,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/get-payment-sources-params.mdx",
   "types/get-plans-params.mdx",
   "types/get-statements-params.mdx",
+  "types/get-subscription-params.mdx",
   "types/get-subscriptions-params.mdx",
   "types/get-token.mdx",
   "types/id-selectors.mdx",

packages/clerk-js/src/core/modules/commerce/CommerceBilling.ts

@@ -8,12 +8,15 @@ import type {
   CommercePlanResource,
   CommerceStatementJSON,
   CommerceStatementResource,
+  CommerceSubscriptionItemJSON,
+  CommerceSubscriptionItemResource,
   CommerceSubscriptionJSON,
   CommerceSubscriptionResource,
   CreateCheckoutParams,
   GetPaymentAttemptsParams,
   GetPlansParams,
   GetStatementsParams,
+  GetSubscriptionParams,
   GetSubscriptionsParams,
 } from '@clerk/types';
 
@@ -25,6 +28,7 @@ import {
   CommercePlan,
   CommerceStatement,
   CommerceSubscription,
+  CommerceSubscriptionItem,
 } from '../../resources/internal';
 
 export class CommerceBilling implements CommerceBillingNamespace {
@@ -45,6 +49,7 @@ export class CommerceBilling implements CommerceBillingNamespace {
     });
   };
 
+  // Inconsistent API
   getPlan = async (params: { id: string }): Promise<CommercePlanResource> => {
     const plan = (await BaseResource._fetch({
       path: `/commerce/plans/${params.id}`,
@@ -53,9 +58,16 @@ export class CommerceBilling implements CommerceBillingNamespace {
     return new CommercePlan(plan);
   };
 
+  getSubscription = async (params: GetSubscriptionParams): Promise<CommerceSubscriptionResource> => {
+    return await BaseResource._fetch({
+      path: params.orgId ? `/organizations/${params.orgId}/commerce/subscription` : `/me/commerce/subscription`,
+      method: 'GET',
+    }).then(res => new CommerceSubscription(res?.response as CommerceSubscriptionJSON));
+  };
+
   getSubscriptions = async (
     params: GetSubscriptionsParams,
-  ): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
+  ): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
     const { orgId, ...rest } = params;
 
     return await BaseResource._fetch({
@@ -64,11 +76,11 @@ export class CommerceBilling implements CommerceBillingNamespace {
       search: convertPageToOffsetSearchParams(rest),
     }).then(res => {
       const { data: subscriptions, total_count } =
-        res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
+        res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;
 
       return {
         total_count,
-        data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
+        data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
       };
     });
   };

packages/clerk-js/src/core/resources/CommercePayment.ts

@@ -3,22 +3,27 @@ import type {
   CommercePaymentChargeType,
   CommercePaymentJSON,
   CommercePaymentResource,
+  CommercePaymentSourceResource,
   CommercePaymentStatus,
+  CommerceSubscriptionItemResource,
 } from '@clerk/types';
 
 import { commerceMoneyFromJSON } from '../../utils';
 import { unixEpochToDate } from '../../utils/date';
-import { BaseResource, CommercePaymentSource, CommerceSubscription } from './internal';
+import { BaseResource, CommercePaymentSource, CommerceSubscriptionItem } from './internal';
 
 export class CommercePayment extends BaseResource implements CommercePaymentResource {
   id!: string;
   amount!: CommerceMoney;
   failedAt?: Date;
   paidAt?: Date;
   updatedAt!: Date;
-  paymentSource!: CommercePaymentSource;
-  subscription!: CommerceSubscription;
-  subscriptionItem!: CommerceSubscription;
+  paymentSource!: CommercePaymentSourceResource;
+  /**
+   * @deprecated
+   */
+  subscription!: CommerceSubscriptionItemResource;
+  subscriptionItem!: CommerceSubscriptionItemResource;
   chargeType!: CommercePaymentChargeType;
   status!: CommercePaymentStatus;
 
@@ -38,8 +43,8 @@ export class CommercePayment extends BaseResource implements CommercePaymentReso
     this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
     this.updatedAt = unixEpochToDate(data.updated_at);
     this.paymentSource = new CommercePaymentSource(data.payment_source);
-    this.subscription = new CommerceSubscription(data.subscription);
-    this.subscriptionItem = new CommerceSubscription(data.subscription_item);
+    this.subscription = new CommerceSubscriptionItem(data.subscription);
+    this.subscriptionItem = new CommerceSubscriptionItem(data.subscription_item);
     this.chargeType = data.charge_type;
     this.status = data.status;
     return this;

packages/clerk-js/src/core/resources/CommerceSubscription.ts

@@ -1,6 +1,8 @@
 import type {
   CancelSubscriptionParams,
   CommerceMoney,
+  CommerceSubscriptionItemJSON,
+  CommerceSubscriptionItemResource,
   CommerceSubscriptionJSON,
   CommerceSubscriptionPlanPeriod,
   CommerceSubscriptionResource,
@@ -14,6 +16,46 @@ import { commerceMoneyFromJSON } from '../../utils';
 import { BaseResource, CommercePlan, DeletedObject } from './internal';
 
 export class CommerceSubscription extends BaseResource implements CommerceSubscriptionResource {
+  id!: string;
+  status!: Extract<CommerceSubscriptionStatus, 'active' | 'past_due'>;
+  activeAt!: Date;
+  createdAt!: Date;
+  pastDueAt!: Date | null;
+  updatedAt!: Date | null;
+  nextPayment: {
+    amount: CommerceMoney;
+    date: Date;
+  } | null = null;
+  subscriptionItems!: CommerceSubscriptionItemResource[];
+
+  constructor(data: CommerceSubscriptionJSON) {
+    super();
+    this.fromJSON(data);
+  }
+
+  protected fromJSON(data: CommerceSubscriptionJSON | null): this {
+    if (!data) {
+      return this;
+    }
+
+    this.id = data.id;
+    this.status = data.status;
+    this.createdAt = unixEpochToDate(data.created_at);
+    this.updatedAt = data.updated_at ? unixEpochToDate(data.updated_at) : null;
+    this.activeAt = unixEpochToDate(data.active_at);
+    this.pastDueAt = data.past_due_at ? unixEpochToDate(data.past_due_at) : null;
+    this.nextPayment = data.next_payment
+      ? {
+          amount: commerceMoneyFromJSON(data.next_payment.amount),
+          date: unixEpochToDate(data.next_payment.date),
+        }
+      : null;
+    this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
+    return this;
+  }
+}
+
+export class CommerceSubscriptionItem extends BaseResource implements CommerceSubscriptionItemResource {
   id!: string;
   paymentSourceId!: string;
   plan!: CommercePlan;
@@ -27,17 +69,18 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
   periodStart!: number;
   periodEnd!: number;
   canceledAt!: number | null;
+  //TODO(@COMMERCE): Why can this be undefined ?
   amount?: CommerceMoney;
   credit?: {
     amount: CommerceMoney;
   };
 
-  constructor(data: CommerceSubscriptionJSON) {
+  constructor(data: CommerceSubscriptionItemJSON) {
     super();
     this.fromJSON(data);
   }
 
-  protected fromJSON(data: CommerceSubscriptionJSON | null): this {
+  protected fromJSON(data: CommerceSubscriptionItemJSON | null): this {
     if (!data) {
       return this;
     }

packages/clerk-js/src/core/resources/Organization.ts

@@ -2,8 +2,8 @@ import type {
   AddMemberParams,
   ClerkPaginatedResponse,
   ClerkResourceReloadParams,
-  CommerceSubscriptionJSON,
-  CommerceSubscriptionResource,
+  CommerceSubscriptionItemJSON,
+  CommerceSubscriptionItemResource,
   CreateOrganizationParams,
   GetDomainsParams,
   GetInvitationsParams,
@@ -32,7 +32,7 @@ import type {
 import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
 import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/commerce';
-import { BaseResource, CommerceSubscription, OrganizationInvitation, OrganizationMembership } from './internal';
+import { BaseResource, CommerceSubscriptionItem, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
 import { Role } from './Role';
@@ -235,18 +235,18 @@ export class Organization extends BaseResource implements OrganizationResource {
 
   getSubscriptions = async (
     getSubscriptionsParams?: GetSubscriptionsParams,
-  ): Promise<ClerkPaginatedResponse<CommerceSubscriptionResource>> => {
+  ): Promise<ClerkPaginatedResponse<CommerceSubscriptionItemResource>> => {
     return await BaseResource._fetch({
       path: `/organizations/${this.id}/commerce/subscriptions`,
       method: 'GET',
       search: convertPageToOffsetSearchParams(getSubscriptionsParams),
     }).then(res => {
       const { data: subscriptions, total_count } =
-        res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionJSON>;
+        res?.response as unknown as ClerkPaginatedResponse<CommerceSubscriptionItemJSON>;
 
       return {
         total_count,
-        data: subscriptions.map(subscription => new CommerceSubscription(subscription)),
+        data: subscriptions.map(subscription => new CommerceSubscriptionItem(subscription)),
       };
     });
   };

packages/clerk-js/src/ui/components/PricingTable/PricingTable.tsx

@@ -2,28 +2,29 @@ import { useClerk } from '@clerk/shared/react';
 import type { CommercePlanResource, CommerceSubscriptionPlanPeriod, PricingTableProps } from '@clerk/types';
 import { useEffect, useMemo, useState } from 'react';
 
-import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscriptions } from '../../contexts';
-import { Flow } from '../../customizables';
+import { Flow } from '@/ui/customizables/Flow';
+
+import { usePaymentMethods, usePlans, usePlansContext, usePricingTableContext, useSubscription } from '../../contexts';
 import { PricingTableDefault } from './PricingTableDefault';
 import { PricingTableMatrix } from './PricingTableMatrix';
 
 const PricingTableRoot = (props: PricingTableProps) => {
   const clerk = useClerk();
   const { mode = 'mounted', signInMode = 'redirect' } = usePricingTableContext();
   const isCompact = mode === 'modal';
-  const { data: subscriptions } = useSubscriptions();
+  const { subscriptionItems } = useSubscription();
   const { data: plans } = usePlans();
   const { handleSelectPlan } = usePlansContext();
 
   const defaultPlanPeriod = useMemo(() => {
     if (isCompact) {
-      const upcomingSubscription = subscriptions?.find(sub => sub.status === 'upcoming');
+      const upcomingSubscription = subscriptionItems?.find(sub => sub.status === 'upcoming');
       if (upcomingSubscription) {
         return upcomingSubscription.planPeriod;
       }
 
       // don't pay attention to the default plan
-      const activeSubscription = subscriptions?.find(
+      const activeSubscription = subscriptionItems?.find(
         sub => !sub.canceledAtDate && sub.status === 'active' && !sub.plan.isDefault,
       );
       if (activeSubscription) {
@@ -32,7 +33,7 @@ const PricingTableRoot = (props: PricingTableProps) => {
     }
 
     return 'annual';
-  }, [isCompact, subscriptions]);
+  }, [isCompact, subscriptionItems]);
 
   const [planPeriod, setPlanPeriod] = useState<CommerceSubscriptionPlanPeriod>(defaultPlanPeriod);