chore(shared,clerk-js): Align for payer type across billing APIs

.changeset/some-parents-begin.md

@@ -0,0 +1,9 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+[Billing Beta]: Replace `org` for `organization` as payer type for billing APIs.
+
+This applies for all billing APIs, except the resources classes that represent data from Frontend API.

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

@@ -32,7 +32,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/commerce-initialized-payment-source-resource.mdx",
   "types/commerce-money-json.mdx",
   "types/commerce-money.mdx",
-  "types/commerce-payer-type.mdx",
+  "types/commerce-payer-resource-type.mdx",
   "types/commerce-payment-charge-type.mdx",
   "types/commerce-payment-json.mdx",
   "types/commerce-payment-resource.mdx",
@@ -66,6 +66,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/experimental_checkout-button-props.mdx",
   "types/experimental_plan-details-button-props.mdx",
   "types/experimental_subscription-details-button-props.mdx",
+  "types/for-payer-type.mdx",
   "types/get-payment-attempts-params.mdx",
   "types/get-payment-sources-params.mdx",
   "types/get-plans-params.mdx",

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

@@ -34,7 +34,7 @@ import {
 export class CommerceBilling implements CommerceBillingNamespace {
   getPlans = async (params?: GetPlansParams): Promise<ClerkPaginatedResponse<CommercePlanResource>> => {
     const { for: forParam, ...safeParams } = params || {};
-    const searchParams = { ...safeParams, payer_type: forParam || 'user' };
+    const searchParams = { ...safeParams, payer_type: forParam === 'organization' ? 'org' : 'user' };
     return await BaseResource._fetch({
       path: `/commerce/plans`,
       method: 'GET',

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

@@ -1,4 +1,9 @@
-import type { CommercePayerType, CommercePlanJSON, CommercePlanJSONSnapshot, CommercePlanResource } from '@clerk/types';
+import type {
+  CommercePayerResourceType,
+  CommercePlanJSON,
+  CommercePlanJSONSnapshot,
+  CommercePlanResource,
+} from '@clerk/types';
 
 import { BaseResource, CommerceFeature } from './internal';
 
@@ -17,7 +22,7 @@ export class CommercePlan extends BaseResource implements CommercePlanResource {
   isDefault!: boolean;
   isRecurring!: boolean;
   hasBaseFee!: boolean;
-  forPayerType!: CommercePayerType;
+  forPayerType!: CommercePayerResourceType;
   publiclyVisible!: boolean;
   slug!: string;
   avatarUrl!: string;

packages/clerk-js/src/ui/components/Checkout/CheckoutForm.tsx

@@ -115,7 +115,7 @@ export const CheckoutForm = withCardStateProvider(() => {
 
 const useCheckoutMutations = () => {
   const { organization } = useOrganization();
-  const { subscriberType, onSubscriptionComplete } = useCheckoutContext();
+  const { for: _for, onSubscriptionComplete } = useCheckoutContext();
   const { checkout } = useCheckout();
   const { id, confirm } = checkout;
   const card = useCardState();
@@ -130,7 +130,8 @@ const useCheckoutMutations = () => {
 
     const { data, error } = await confirm({
       ...params,
-      ...(subscriberType === 'org' ? { orgId: organization?.id } : {}),
+      // TODO(@COMMERCE): Come back to this, this should not be needed
+      ...(_for === 'organization' ? { orgId: organization?.id } : {}),
     });
 
     if (error) {

packages/clerk-js/src/ui/components/Checkout/CheckoutPage.tsx

@@ -10,18 +10,18 @@ const Initiator = () => {
   const { checkout } = useCheckout();
 
   useEffect(() => {
-    checkout.start().catch(() => null);
+    void checkout.start();
     return checkout.clear;
   }, []);
   return null;
 };
 
 const Root = ({ children }: { children: React.ReactNode }) => {
-  const { planId, planPeriod, subscriberType } = useCheckoutContext();
+  const { planId, planPeriod, for: _for } = useCheckoutContext();
 
   return (
     <CheckoutProvider
-      for={subscriberType === 'org' ? 'organization' : undefined}
+      for={_for}
       planId={
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         planId!

packages/clerk-js/src/ui/components/Checkout/index.tsx

@@ -13,7 +13,7 @@ export const Checkout = (props: __internal_CheckoutProps) => {
   return (
     <Flow.Root flow='checkout'>
       <Flow.Part>
-        <SubscriberTypeContext.Provider value={props.subscriberType || 'user'}>
+        <SubscriberTypeContext.Provider value={props.for || 'user'}>
           <CheckoutContext.Provider
             value={{
               componentName: 'Checkout',

packages/clerk-js/src/ui/components/OrganizationProfile/OrganizationBillingPage.tsx

@@ -83,7 +83,7 @@ const OrganizationBillingPageInternal = withCardStateProvider(() => {
 
 export const OrganizationBillingPage = () => {
   return (
-    <SubscriberTypeContext.Provider value='org'>
+    <SubscriberTypeContext.Provider value='organization'>
       <OrganizationBillingPageInternal />
     </SubscriberTypeContext.Provider>
   );

packages/clerk-js/src/ui/components/OrganizationProfile/OrganizationPaymentAttemptPage.tsx

@@ -3,7 +3,7 @@ import { PaymentAttemptPage } from '../PaymentAttempts';
 
 export const OrganizationPaymentAttemptPage = () => {
   return (
-    <SubscriberTypeContext.Provider value='org'>
+    <SubscriberTypeContext.Provider value='organization'>
       <PaymentAttemptPage />
     </SubscriberTypeContext.Provider>
   );

packages/clerk-js/src/ui/components/OrganizationProfile/OrganizationPlansPage.tsx

@@ -53,7 +53,7 @@ const OrganizationPlansPageInternal = () => {
 
 export const OrganizationPlansPage = () => {
   return (
-    <SubscriberTypeContext.Provider value='org'>
+    <SubscriberTypeContext.Provider value='organization'>
       <OrganizationPlansPageInternal />
     </SubscriberTypeContext.Provider>
   );

packages/clerk-js/src/ui/components/OrganizationProfile/OrganizationStatementPage.tsx

@@ -3,7 +3,7 @@ import { StatementPage } from '../Statements';
 
 export const OrganizationStatementPage = () => {
   return (
-    <SubscriberTypeContext.Provider value='org'>
+    <SubscriberTypeContext.Provider value='organization'>
       <StatementPage />
     </SubscriberTypeContext.Provider>
   );

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

@@ -25,7 +25,7 @@ const AddScreen = withCardStateProvider(({ onSuccess }: { onSuccess: () => void
   const localizationRoot = useSubscriberTypeLocalizationRoot();
 
   const onAddPaymentSourceSuccess = async (context: { gateway: 'stripe'; paymentToken: string }) => {
-    const resource = subscriberType === 'org' ? clerk?.organization : clerk.user;
+    const resource = subscriberType === 'organization' ? clerk?.organization : clerk.user;
     await resource?.addPaymentSource(context);
     onSuccess();
     close();
@@ -72,7 +72,7 @@ const RemoveScreen = ({
 
   const removePaymentSource = async () => {
     await paymentSource
-      .remove({ orgId: subscriberType === 'org' ? organization?.id : undefined })
+      .remove({ orgId: subscriberType === 'organization' ? organization?.id : undefined })
       .then(revalidate)
       .catch((error: Error) => {
         handleError(error, [], card.setError);
@@ -108,7 +108,7 @@ export const PaymentSources = withCardStateProvider(() => {
   const clerk = useClerk();
   const subscriberType = useSubscriberTypeContext();
   const localizationRoot = useSubscriberTypeLocalizationRoot();
-  const resource = subscriberType === 'org' ? clerk?.organization : clerk.user;
+  const resource = subscriberType === 'organization' ? clerk?.organization : clerk.user;
 
   const { data: paymentMethods, isLoading, revalidate: revalidatePaymentMethods } = usePaymentMethods();
 
@@ -209,7 +209,7 @@ const PaymentSourceMenu = ({
       isDestructive: false,
       onClick: () => {
         paymentSource
-          .makeDefault({ orgId: subscriberType === 'org' ? organization?.id : undefined })
+          .makeDefault({ orgId: subscriberType === 'organization' ? organization?.id : undefined })
           .then(revalidate)
           .catch((error: Error) => {
             handleError(error, [], card.setError);

packages/clerk-js/src/ui/components/Plans/PlanDetails.tsx

@@ -58,7 +58,7 @@ const PlanDetailsInternal = ({
   const hasFeatures = features.length > 0;
 
   return (
-    <SubscriberTypeContext.Provider value={plan.forPayerType}>
+    <SubscriberTypeContext.Provider value={plan.forPayerType === 'org' ? 'organization' : 'user'}>
       <Drawer.Header
         sx={t =>
           !hasFeatures

packages/clerk-js/src/ui/components/SubscriptionDetails/index.tsx

@@ -189,7 +189,7 @@ const SubscriptionDetailsFooter = withCardStateProvider(() => {
     setLoading();
 
     await selectedSubscription
-      .cancel({ orgId: subscriberType === 'org' ? organization?.id : undefined })
+      .cancel({ orgId: subscriberType === 'organization' ? organization?.id : undefined })
       .then(() => {
         onSubscriptionCancel?.();
         if (setIsOpen) {
@@ -381,7 +381,7 @@ const SubscriptionCardActions = ({ subscription }: { subscription: CommerceSubsc
               openCheckout({
                 planId: subscription.plan.id,
                 planPeriod: subscription.planPeriod === 'month' ? 'annual' : 'month',
-                subscriberType,
+                for: subscriberType,
               });
             },
           }
@@ -403,7 +403,7 @@ const SubscriptionCardActions = ({ subscription }: { subscription: CommerceSubsc
               openCheckout({
                 planId: subscription.plan.id,
                 planPeriod: subscription.planPeriod,
-                subscriberType,
+                for: subscriberType,
               });
             },
           }

packages/clerk-js/src/ui/components/Subscriptions/SubscriptionsList.tsx

@@ -197,7 +197,7 @@ export function SubscriptionsList({
       )}
 
       {(commerceSettings.billing.user.hasPaidPlans && subscriberType === 'user') ||
-      (commerceSettings.billing.organization.hasPaidPlans && subscriberType === 'org') ? (
+      (commerceSettings.billing.organization.hasPaidPlans && subscriberType === 'organization') ? (
         <ProfileSection.ArrowButton
           id='subscriptionsList'
           textLocalizationKey={subscriptionItems.length > 0 ? arrowButtonText : arrowButtonEmptyText}

packages/clerk-js/src/ui/contexts/ClerkUIComponentsContext.tsx

@@ -92,7 +92,7 @@ export function ComponentContextProvider({
       );
     case 'PricingTable':
       return (
-        <SubscriberTypeContext.Provider value={(props as PricingTableProps).forOrganizations ? 'org' : 'user'}>
+        <SubscriberTypeContext.Provider value={(props as PricingTableProps).forOrganizations ? 'organization' : 'user'}>
           <PricingTableContext.Provider value={{ componentName, ...(props as PricingTableProps) }}>
             {children}
           </PricingTableContext.Provider>

packages/clerk-js/src/ui/contexts/components/Checkout.ts

@@ -5,12 +5,6 @@ import { isAllowedRedirect } from '../../../utils';
 import type { CheckoutCtx } from '../../types';
 import { useOptions } from '../OptionsContext';
 
-function invariant(cond: any, msg: string): asserts cond {
-  if (!cond) {
-    throw Error(msg);
-  }
-}
-
 export const CheckoutContext = createContext<CheckoutCtx | null>(null);
 
 export const useCheckoutContext = () => {
@@ -35,22 +29,9 @@ export const useCheckoutContext = () => {
 
   const { componentName, ...ctx } = context;
 
-  const subscriber = () => {
-    if (ctx.subscriberType === 'org' && clerk.organization) {
-      invariant(clerk.organization, 'Clerk: subscriberType is "org" but no active organization was found');
-
-      return clerk.organization;
-    }
-
-    invariant(clerk.user, 'Clerk: no active user found');
-
-    return clerk.user;
-  };
-
   return {
     ...ctx,
     componentName,
     newSubscriptionRedirectUrl,
-    subscriber,
   };
 };

packages/clerk-js/src/ui/contexts/components/Plans.tsx

@@ -25,7 +25,7 @@ import { useSubscriberTypeContext } from './SubscriberType';
 export const usePaymentMethods = () => {
   const subscriberType = useSubscriberTypeContext();
   return __experimental_usePaymentMethods({
-    for: subscriberType === 'org' ? 'organization' : 'user',
+    for: subscriberType,
     initialPage: 1,
     pageSize: 10,
     keepPreviousData: true,
@@ -35,7 +35,7 @@ export const usePaymentMethods = () => {
 export const usePaymentAttempts = () => {
   const subscriberType = useSubscriberTypeContext();
   return __experimental_usePaymentAttempts({
-    for: subscriberType === 'org' ? 'organization' : 'user',
+    for: subscriberType,
     initialPage: 1,
     pageSize: 10,
     keepPreviousData: true,
@@ -45,7 +45,7 @@ export const usePaymentAttempts = () => {
 export const useStatements = (params?: { mode: 'cache' }) => {
   const subscriberType = useSubscriberTypeContext();
   return __experimental_useStatements({
-    for: subscriberType === 'org' ? 'organization' : 'user',
+    for: subscriberType,
     initialPage: 1,
     pageSize: 10,
     keepPreviousData: true,
@@ -56,7 +56,7 @@ export const useStatements = (params?: { mode: 'cache' }) => {
 export const useSubscription = () => {
   const subscriberType = useSubscriberTypeContext();
   const subscription = __experimental_useSubscription({
-    for: subscriberType === 'org' ? 'organization' : 'user',
+    for: subscriberType,
     keepPreviousData: true,
   });
   const subscriptionItems = useMemo(
@@ -74,7 +74,7 @@ export const usePlans = (params?: { mode: 'cache' }) => {
   const subscriberType = useSubscriberTypeContext();
 
   return __experimental_usePlans({
-    for: subscriberType === 'org' ? 'organization' : 'user',
+    for: subscriberType,
     initialPage: 1,
     pageSize: 50,
     keepPreviousData: true,
@@ -303,7 +303,7 @@ export const usePlansContext = () => {
         planId: plan.id,
         // if the plan doesn't support annual, use monthly
         planPeriod: planPeriod === 'annual' && plan.annualMonthlyAmount === 0 ? 'month' : planPeriod,
-        subscriberType,
+        for: subscriberType,
         onSubscriptionComplete: () => {
           revalidateAll();
         },

packages/clerk-js/src/ui/contexts/components/SubscriberType.ts

@@ -1,10 +1,10 @@
-import type { CommercePayerType } from '@clerk/types';
+import type { ForPayerType } from '@clerk/types';
 import { createContext, useContext } from 'react';
 
 const DEFAUlT = 'user';
-export const SubscriberTypeContext = createContext<CommercePayerType | undefined>(DEFAUlT);
+export const SubscriberTypeContext = createContext<ForPayerType | undefined>(DEFAUlT);
 
-export const useSubscriberTypeContext = (): CommercePayerType => useContext(SubscriberTypeContext) || DEFAUlT;
+export const useSubscriberTypeContext = (): ForPayerType => useContext(SubscriberTypeContext) || DEFAUlT;
 
 export const useSubscriberTypeLocalizationRoot = () => {
   const subscriberType = useSubscriberTypeContext();

packages/clerk-js/src/ui/lazyModules/MountedCheckoutDrawer.tsx

@@ -40,7 +40,7 @@ export function MountedCheckoutDrawer({
         <Checkout
           planId={checkoutDrawer.props.planId}
           planPeriod={checkoutDrawer.props.planPeriod}
-          subscriberType={checkoutDrawer.props.subscriberType}
+          for={checkoutDrawer.props.for}
           onSubscriptionComplete={checkoutDrawer.props.onSubscriptionComplete}
           portalRoot={checkoutDrawer.props.portalRoot}
           appearance={checkoutDrawer.props.appearance}

packages/react/src/components/CheckoutButton.tsx

@@ -49,7 +49,7 @@ export const CheckoutButton = withClerk(
     const {
       planId,
       planPeriod,
-      subscriberType,
+      for: _for,
       onSubscriptionComplete,
       newSubscriptionRedirectUrl,
       checkoutProps,
@@ -62,7 +62,7 @@ export const CheckoutButton = withClerk(
       throw new Error('Ensure that `<CheckoutButton />` is rendered inside a `<SignedIn />` component.');
     }
 
-    if (orgId === null && subscriberType === 'org') {
+    if (orgId === null && _for === 'organization') {
       throw new Error('Wrap `<CheckoutButton for="organization" />` with a check for an active organization.');
     }
 
@@ -77,7 +77,7 @@ export const CheckoutButton = withClerk(
       return clerk.__internal_openCheckout({
         planId,
         planPeriod,
-        subscriberType,
+        for: _for,
         onSubscriptionComplete,
         newSubscriptionRedirectUrl,
         ...checkoutProps,

packages/react/src/components/SubscriptionDetailsButton.tsx

@@ -46,7 +46,7 @@ export const SubscriptionDetailsButton = withClerk(
     children,
     ...props
   }: WithClerkProp<React.PropsWithChildren<__experimental_SubscriptionDetailsButtonProps>>) => {
-    const { for: forProp, subscriptionDetailsProps, onSubscriptionCancel, ...rest } = props;
+    const { for: _for, subscriptionDetailsProps, onSubscriptionCancel, ...rest } = props;
     children = normalizeWithDefaultValue(children, 'Subscription details');
     const child = assertSingleChild(children)('SubscriptionDetailsButton');
 
@@ -56,7 +56,7 @@ export const SubscriptionDetailsButton = withClerk(
       throw new Error('Ensure that `<SubscriptionDetailsButton />` is rendered inside a `<SignedIn />` component.');
     }
 
-    if (orgId === null && forProp === 'org') {
+    if (orgId === null && _for === 'organization') {
       throw new Error(
         'Wrap `<SubscriptionDetailsButton for="organization" />` with a check for an active organization.',
       );
@@ -68,7 +68,7 @@ export const SubscriptionDetailsButton = withClerk(
       }
 
       return clerk.__internal_openSubscriptionDetails({
-        for: forProp,
+        for: _for,
         onSubscriptionCancel,
         ...subscriptionDetailsProps,
       });