chore(clerk-js,types): Update checkout flow to support free trials

.changeset/rotten-lines-cough.md

@@ -0,0 +1,9 @@
+---
+'@clerk/localizations': minor
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Add support for trials in `<Checkout/>`
+  - Added `freeTrialEndsAt` property to `CommerceCheckoutResource` interface.

packages/clerk-js/bundlewatch.config.json

@@ -1,6 +1,6 @@
 {
   "files": [
-    { "path": "./dist/clerk.js", "maxSize": "622KB" },
+    { "path": "./dist/clerk.js", "maxSize": "622.1KB" },
     { "path": "./dist/clerk.browser.js", "maxSize": "76KB" },
     { "path": "./dist/clerk.legacy.browser.js", "maxSize": "117KB" },
     { "path": "./dist/clerk.headless*.js", "maxSize": "58KB" },
@@ -23,7 +23,7 @@
     { "path": "./dist/waitlist*.js", "maxSize": "1.5KB" },
     { "path": "./dist/keylessPrompt*.js", "maxSize": "6.5KB" },
     { "path": "./dist/pricingTable*.js", "maxSize": "4.02KB" },
-    { "path": "./dist/checkout*.js", "maxSize": "8.5KB" },
+    { "path": "./dist/checkout*.js", "maxSize": "8.75KB" },
     { "path": "./dist/up-billing-page*.js", "maxSize": "3.0KB" },
     { "path": "./dist/op-billing-page*.js", "maxSize": "3.0KB" },
     { "path": "./dist/up-plans-page*.js", "maxSize": "1.0KB" },

packages/clerk-js/jest.setup.ts

@@ -33,7 +33,7 @@ if (typeof window !== 'undefined') {
     })),
   });
 
-  //@ts-expect-error
+  //@ts-expect-error - JSDOM doesn't provide IntersectionObserver, so we mock it for testing
   global.IntersectionObserver = class IntersectionObserver {
     constructor() {}
 
@@ -53,4 +53,18 @@ if (typeof window !== 'undefined') {
       return null;
     }
   };
+
+  // Mock HTMLCanvasElement.prototype.getContext to prevent errors
+  HTMLCanvasElement.prototype.getContext = jest.fn().mockImplementation(((contextType: string) => {
+    if (contextType === '2d') {
+      return {
+        fillRect: jest.fn(),
+        getImageData: jest.fn(() => ({ data: new Uint8ClampedArray([255, 255, 255, 255]) }) as unknown as ImageData),
+      } as unknown as CanvasRenderingContext2D;
+    }
+    if (contextType === 'webgl' || contextType === 'webgl2') {
+      return {} as unknown as WebGLRenderingContext;
+    }
+    return null;
+  }) as any) as jest.MockedFunction<HTMLCanvasElement['getContext']>;
 }

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

@@ -7,6 +7,8 @@ import type {
   ConfirmCheckoutParams,
 } from '@clerk/types';
 
+import { unixEpochToDate } from '@/utils/date';
+
 import { commerceTotalsFromJSON } from '../../utils';
 import { BaseResource, CommercePaymentSource, CommercePlan, isClerkAPIResponseError } from './internal';
 
@@ -21,6 +23,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
   status!: 'needs_confirmation' | 'completed';
   totals!: CommerceCheckoutTotals;
   isImmediatePlanChange!: boolean;
+  freeTrialEndsAt!: Date | null;
 
   constructor(data: CommerceCheckoutJSON, orgId?: string) {
     super();
@@ -43,6 +46,7 @@ export class CommerceCheckout extends BaseResource implements CommerceCheckoutRe
     this.status = data.status;
     this.totals = commerceTotalsFromJSON(data.totals);
     this.isImmediatePlanChange = data.is_immediate_plan_change;
+    this.freeTrialEndsAt = data.free_trial_ends_at ? unixEpochToDate(data.free_trial_ends_at) : null;
     return this;
   }
 

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

@@ -52,7 +52,7 @@ export class CommerceSubscription extends BaseResource implements CommerceSubscr
         }
       : null;
     this.subscriptionItems = (data.subscription_items || []).map(item => new CommerceSubscriptionItem(item));
-    this.eligibleForFreeTrial = data.eligible_for_free_trial;
+    this.eligibleForFreeTrial = this.withDefault(data.eligible_for_free_trial, false);
     return this;
   }
 }

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

@@ -19,7 +19,7 @@ export const CheckoutComplete = () => {
   const { setIsOpen } = useDrawerContext();
   const { newSubscriptionRedirectUrl } = useCheckoutContext();
   const { checkout } = useCheckout();
-  const { totals, paymentSource, planPeriodStart } = checkout;
+  const { totals, paymentSource, planPeriodStart, freeTrialEndsAt } = checkout;
   const [mousePosition, setMousePosition] = useState({ x: 256, y: 256 });
   const [currentPosition, setCurrentPosition] = useState({ x: 256, y: 256 });
 
@@ -310,9 +310,11 @@ export const CheckoutComplete = () => {
               as='h2'
               textVariant='h2'
               localizationKey={
-                totals.totalDueNow.amount > 0
-                  ? localizationKeys('commerce.checkout.title__paymentSuccessful')
-                  : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
+                freeTrialEndsAt
+                  ? localizationKeys('commerce.checkout.title__trialSuccess')
+                  : totals.totalDueNow.amount > 0
+                    ? localizationKeys('commerce.checkout.title__paymentSuccessful')
+                    : localizationKeys('commerce.checkout.title__subscriptionSuccessful')
               }
               sx={t => ({
                 opacity: 0,
@@ -399,17 +401,24 @@ export const CheckoutComplete = () => {
             <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__totalPaid')} />
             <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
           </LineItems.Group>
+
+          {freeTrialEndsAt ? (
+            <LineItems.Group variant='secondary'>
+              <LineItems.Title title={localizationKeys('commerce.checkout.lineItems.title__freeTrialEndsAt')} />
+              <LineItems.Description text={formatDate(freeTrialEndsAt)} />
+            </LineItems.Group>
+          ) : null}
           <LineItems.Group variant='secondary'>
             <LineItems.Title
               title={
-                totals.totalDueNow.amount > 0
+                totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
                   ? localizationKeys('commerce.checkout.lineItems.title__paymentMethod')
                   : localizationKeys('commerce.checkout.lineItems.title__subscriptionBegins')
               }
             />
             <LineItems.Description
               text={
-                totals.totalDueNow.amount > 0
+                totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
                   ? paymentSource
                     ? paymentSource.paymentMethod !== 'card'
                       ? `${capitalize(paymentSource.paymentMethod)}`

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

@@ -17,6 +17,7 @@ import { Box, Button, Col, descriptors, Flex, Form, localizationKeys, Text } fro
 import { ChevronUpDown, InformationCircle } from '../../icons';
 import * as AddPaymentSource from '../PaymentSources/AddPaymentSource';
 import { PaymentSourceRow } from '../PaymentSources/PaymentSourceRow';
+import { SubscriptionBadge } from '../Subscriptions/badge';
 
 type PaymentMethodSource = 'existing' | 'new';
 
@@ -25,7 +26,7 @@ const capitalize = (name: string) => name[0].toUpperCase() + name.slice(1);
 export const CheckoutForm = withCardStateProvider(() => {
   const { checkout } = useCheckout();
 
-  const { id, plan, totals, isImmediatePlanChange, planPeriod } = checkout;
+  const { id, plan, totals, isImmediatePlanChange, planPeriod, freeTrialEndsAt } = checkout;
 
   if (!id) {
     return null;
@@ -53,6 +54,11 @@ export const CheckoutForm = withCardStateProvider(() => {
             <LineItems.Title
               title={plan.name}
               description={planPeriod === 'annual' ? localizationKeys('commerce.billedAnnually') : undefined}
+              badge={
+                plan.freeTrialEnabled && freeTrialEndsAt ? (
+                  <SubscriptionBadge subscription={{ status: 'free_trial' }} />
+                ) : null
+              }
             />
             <LineItems.Description
               prefix={planPeriod === 'annual' ? 'x12' : undefined}
@@ -87,6 +93,20 @@ export const CheckoutForm = withCardStateProvider(() => {
               <LineItems.Description text={`${totals.pastDue?.currencySymbol}${totals.pastDue?.amountFormatted}`} />
             </LineItems.Group>
           )}
+
+          {!!freeTrialEndsAt && !!plan.freeTrialDays && (
+            <LineItems.Group variant='tertiary'>
+              <LineItems.Title
+                title={localizationKeys('commerce.checkout.totalDueAfterTrial', {
+                  days: plan.freeTrialDays,
+                })}
+              />
+              <LineItems.Description
+                text={`${totals.grandTotal?.currencySymbol}${totals.grandTotal?.amountFormatted}`}
+              />
+            </LineItems.Group>
+          )}
+
           <LineItems.Group borderTop>
             <LineItems.Title title={localizationKeys('commerce.totalDueToday')} />
             <LineItems.Description text={`${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`} />
@@ -278,15 +298,32 @@ export const PayWithTestPaymentSource = () => {
   );
 };
 
-const AddPaymentSourceForCheckout = withCardStateProvider(() => {
-  const { addPaymentSourceAndPay } = useCheckoutMutations();
+const useSubmitLabel = () => {
   const { checkout } = useCheckout();
-  const { status, totals } = checkout;
+  const { status, freeTrialEndsAt, totals } = checkout;
 
   if (status === 'needs_initialization') {
-    return null;
+    throw new Error('Clerk: Invalid state');
+  }
+
+  if (freeTrialEndsAt) {
+    return localizationKeys('commerce.startFreeTrial');
   }
 
+  if (totals.totalDueNow.amount > 0) {
+    return localizationKeys('commerce.pay', {
+      amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
+    });
+  }
+
+  return localizationKeys('commerce.subscribe');
+};
+
+const AddPaymentSourceForCheckout = withCardStateProvider(() => {
+  const { addPaymentSourceAndPay } = useCheckoutMutations();
+  const submitLabel = useSubmitLabel();
+  const { checkout } = useCheckout();
+
   return (
     <AddPaymentSource.Root
       onSuccess={addPaymentSourceAndPay}
@@ -296,15 +333,7 @@ const AddPaymentSourceForCheckout = withCardStateProvider(() => {
         <PayWithTestPaymentSource />
       </DevOnly>
 
-      {totals.totalDueNow.amount > 0 ? (
-        <AddPaymentSource.FormButton
-          text={localizationKeys('commerce.pay', {
-            amount: `${totals.totalDueNow.currencySymbol}${totals.totalDueNow.amountFormatted}`,
-          })}
-        />
-      ) : (
-        <AddPaymentSource.FormButton text={localizationKeys('commerce.subscribe')} />
-      )}
+      <AddPaymentSource.FormButton text={submitLabel} />
     </AddPaymentSource.Root>
   );
 });
@@ -317,8 +346,9 @@ const ExistingPaymentSourceForm = withCardStateProvider(
     totalDueNow: CommerceMoneyAmount;
     paymentSources: CommercePaymentSourceResource[];
   }) => {
+    const submitLabel = useSubmitLabel();
     const { checkout } = useCheckout();
-    const { paymentSource } = checkout;
+    const { paymentSource, freeTrialEndsAt } = checkout;
 
     const { payWithExistingPaymentSource } = useCheckoutMutations();
     const card = useCardState();
@@ -340,6 +370,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
       });
     }, [paymentSources]);
 
+    const isSchedulePayment = totalDueNow.amount > 0 && !freeTrialEndsAt;
+
     return (
       <Form
         onSubmit={payWithExistingPaymentSource}
@@ -349,7 +381,7 @@ const ExistingPaymentSourceForm = withCardStateProvider(
           rowGap: t.space.$4,
         })}
       >
-        {totalDueNow.amount > 0 ? (
+        {isSchedulePayment ? (
           <Select
             elementId='paymentSource'
             options={options}
@@ -399,17 +431,8 @@ const ExistingPaymentSourceForm = withCardStateProvider(
             width: '100%',
           }}
           isLoading={card.isLoading}
-        >
-          <Text
-            localizationKey={
-              totalDueNow.amount > 0
-                ? localizationKeys('commerce.pay', {
-                    amount: `${totalDueNow.currencySymbol}${totalDueNow.amountFormatted}`,
-                  })
-                : localizationKeys('commerce.subscribe')
-            }
-          />
-        </Button>
+          localizationKey={submitLabel}
+        />
       </Form>
     );
   },