fix(clerk-js, shared, nextjs): Improve typesafety of useCheckout

.changeset/brown-wings-shake.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': minor
+'@clerk/nextjs': minor
+'@clerk/clerk-react': minor
+'@clerk/clerk-js': patch
+---
+
+[Billing Beta] Stricter return type of `useCheckout` to improve inference of other properties.

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

@@ -279,9 +279,9 @@ export const PayWithTestPaymentSource = () => {
 const AddPaymentSourceForCheckout = withCardStateProvider(() => {
   const { addPaymentSourceAndPay } = useCheckoutMutations();
   const { checkout } = useCheckout();
-  const { id, totals } = checkout;
+  const { status, totals } = checkout;
 
-  if (!id) {
+  if (status === 'needs_initialization') {
     return null;
   }
 

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

@@ -62,7 +62,7 @@ const FetchStatus = ({
   const { fetchStatus, error } = checkout;
 
   const internalFetchStatus = useMemo(() => {
-    if (fetchStatus === 'error' && error?.errors) {
+    if (fetchStatus === 'error') {
       const errorCodes = error.errors.map(e => e.code);
 
       if (errorCodes.includes('missing_payer_email')) {
@@ -75,7 +75,7 @@ const FetchStatus = ({
     }
 
     return fetchStatus;
-  }, [fetchStatus, error]);
+  }, [fetchStatus]);
 
   if (internalFetchStatus !== status) {
     return null;

packages/shared/src/react/hooks/__tests__/useCheckout.type.spec.ts

@@ -1,5 +1,6 @@
 import type {
   __experimental_CheckoutCacheState,
+  __experimental_CheckoutInstance,
   ClerkAPIResponseError,
   CommerceCheckoutResource,
   CommerceSubscriptionPlanPeriod,
@@ -158,5 +159,96 @@ describe('useCheckout type tests', () => {
         >();
       });
     });
+
+    describe('discriminated unions', () => {
+      describe('error state discrimination', () => {
+        it('has correct fetchStatus type union', () => {
+          type FetchStatus = CheckoutObject['fetchStatus'];
+          expectTypeOf<FetchStatus>().toEqualTypeOf<'idle' | 'fetching' | 'error'>();
+        });
+
+        it('has correct error type union', () => {
+          type ErrorType = CheckoutObject['error'];
+          expectTypeOf<ErrorType>().toMatchTypeOf<ClerkAPIResponseError | null>();
+        });
+
+        it('enforces error state correlation', () => {
+          // When fetchStatus is 'error', error should not be null
+          type ErrorFetchState = CheckoutObject & { fetchStatus: 'error' };
+          expectTypeOf<ErrorFetchState['error']>().not.toEqualTypeOf<null>();
+
+          // When fetchStatus is not 'error', error must be null
+          type NonErrorFetchState = CheckoutObject & { fetchStatus: 'idle' | 'fetching' };
+          expectTypeOf<NonErrorFetchState['error']>().toEqualTypeOf<null>();
+        });
+      });
+
+      describe('status-based property discrimination', () => {
+        it('has correct status type union', () => {
+          type Status = CheckoutObject['status'];
+          expectTypeOf<Status>().toEqualTypeOf<'needs_initialization' | 'needs_confirmation' | 'completed'>();
+        });
+
+        it('enforces null properties when status is needs_initialization', () => {
+          type InitializationState = CheckoutObject & { status: 'needs_initialization' };
+
+          // Test that properties are nullable (null or undefined) in initialization state
+          expectTypeOf<InitializationState['id']>().toEqualTypeOf<null>();
+          expectTypeOf<InitializationState['externalClientSecret']>().toEqualTypeOf<null>();
+          expectTypeOf<InitializationState['externalGatewayId']>().toEqualTypeOf<null>();
+          expectTypeOf<InitializationState['totals']>().toEqualTypeOf<null>();
+          expectTypeOf<InitializationState['isImmediatePlanChange']>().toEqualTypeOf<null>();
+          expectTypeOf<InitializationState['planPeriod']>().toEqualTypeOf<null>();
+          expectTypeOf<InitializationState['plan']>().toEqualTypeOf<null>();
+          expectTypeOf<InitializationState['paymentSource']>().toEqualTypeOf<null | undefined>();
+
+          // Test that the status property is correctly typed
+          expectTypeOf<InitializationState['status']>().toEqualTypeOf<'needs_initialization'>();
+        });
+
+        it('enforces proper types when status is needs_confirmation or completed', () => {
+          type ConfirmationState = CheckoutObject & { status: 'needs_confirmation' };
+          type CompletedState = CheckoutObject & { status: 'completed' };
+
+          // These should not be null for confirmation and completed states
+          expectTypeOf<ConfirmationState['id']>().not.toEqualTypeOf<null>();
+          expectTypeOf<ConfirmationState['totals']>().not.toEqualTypeOf<null>();
+          expectTypeOf<ConfirmationState['plan']>().not.toEqualTypeOf<null>();
+
+          expectTypeOf<CompletedState['id']>().not.toEqualTypeOf<null>();
+          expectTypeOf<CompletedState['totals']>().not.toEqualTypeOf<null>();
+          expectTypeOf<CompletedState['plan']>().not.toEqualTypeOf<null>();
+        });
+      });
+
+      describe('type structure validation', () => {
+        it('validates the overall discriminated union structure', () => {
+          // Test that CheckoutObject is a proper discriminated union
+          type CheckoutUnion = CheckoutObject;
+
+          // Should include all required properties
+          expectTypeOf<CheckoutUnion>().toHaveProperty('status');
+          expectTypeOf<CheckoutUnion>().toHaveProperty('fetchStatus');
+          expectTypeOf<CheckoutUnion>().toHaveProperty('error');
+          expectTypeOf<CheckoutUnion>().toHaveProperty('id');
+          expectTypeOf<CheckoutUnion>().toHaveProperty('confirm');
+          expectTypeOf<CheckoutUnion>().toHaveProperty('start');
+          expectTypeOf<CheckoutUnion>().toHaveProperty('clear');
+          expectTypeOf<CheckoutUnion>().toHaveProperty('finalize');
+          expectTypeOf<CheckoutUnion>().toHaveProperty('getState');
+          expectTypeOf<CheckoutUnion>().toHaveProperty('isStarting');
+          expectTypeOf<CheckoutUnion>().toHaveProperty('isConfirming');
+        });
+
+        it('validates method types remain unchanged', () => {
+          // Ensure the discriminated union doesn't affect method types
+          expectTypeOf<CheckoutObject['confirm']>().toEqualTypeOf<__experimental_CheckoutInstance['confirm']>();
+          expectTypeOf<CheckoutObject['start']>().toEqualTypeOf<__experimental_CheckoutInstance['start']>();
+          expectTypeOf<CheckoutObject['clear']>().toEqualTypeOf<() => void>();
+          expectTypeOf<CheckoutObject['finalize']>().toEqualTypeOf<(params?: { redirectUrl: string }) => void>();
+          expectTypeOf<CheckoutObject['getState']>().toEqualTypeOf<() => __experimental_CheckoutCacheState>();
+        });
+      });
+    });
   });
 });

packages/shared/src/react/hooks/useCheckout.ts

@@ -28,21 +28,40 @@ type ForceNull<T> = {
 
 type CheckoutProperties = Omit<RemoveFunctions<CommerceCheckoutResource>, 'pathRoot' | 'status'>;
 
-type NullableCheckoutProperties = CheckoutProperties | ForceNull<CheckoutProperties>;
+type FetchStatusAndError =
+  | {
+      error: ClerkAPIResponseError;
+      fetchStatus: 'error';
+    }
+  | {
+      error: null;
+      fetchStatus: 'idle' | 'fetching';
+    };
+
+/**
+ * @internal
+ * On status === 'needs_initialization', all properties are null.
+ * On status === 'needs_confirmation' or 'completed', all properties are defined the same as the CommerceCheckoutResource.
+ */
+type CheckoutPropertiesPerStatus =
+  | ({
+      status: Extract<__experimental_CheckoutCacheState['status'], 'needs_initialization'>;
+    } & ForceNull<CheckoutProperties>)
+  | ({
+      status: Extract<__experimental_CheckoutCacheState['status'], 'needs_confirmation' | 'completed'>;
+    } & CheckoutProperties);
 
 type __experimental_UseCheckoutReturn = {
-  checkout: NullableCheckoutProperties & {
-    confirm: __experimental_CheckoutInstance['confirm'];
-    start: __experimental_CheckoutInstance['start'];
-    isStarting: boolean;
-    isConfirming: boolean;
-    error: ClerkAPIResponseError | null;
-    status: __experimental_CheckoutCacheState['status'];
-    clear: () => void;
-    finalize: (params?: { redirectUrl: string }) => void;
-    fetchStatus: 'idle' | 'fetching' | 'error';
-    getState: () => __experimental_CheckoutCacheState;
-  };
+  checkout: FetchStatusAndError &
+    CheckoutPropertiesPerStatus & {
+      confirm: __experimental_CheckoutInstance['confirm'];
+      start: __experimental_CheckoutInstance['start'];
+      clear: () => void;
+      finalize: (params?: { redirectUrl: string }) => void;
+      getState: () => __experimental_CheckoutCacheState;
+      isStarting: boolean;
+      isConfirming: boolean;
+    };
 };
 
 type Params = Parameters<typeof __experimental_CheckoutProvider>[0];
@@ -74,7 +93,7 @@ export const useCheckout = (options?: Params): __experimental_UseCheckoutReturn
     () => manager.getState(),
   );
 
-  const properties = useMemo<NullableCheckoutProperties>(() => {
+  const properties = useMemo<CheckoutProperties | ForceNull<CheckoutProperties>>(() => {
     if (!managerProperties.checkout) {
       return {
         id: null,
@@ -115,5 +134,5 @@ export const useCheckout = (options?: Params): __experimental_UseCheckoutReturn
 
   return {
     checkout,
-  };
+  } as __experimental_UseCheckoutReturn;
 };