chore(clerk-js,types): Align payment methods terminology

.changeset/rich-breads-move.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': patch
+'@clerk/types': minor
+---
+
+[Billing Beta] Rename payment source to payment method.

packages/clerk-js/src/core/modules/billing/namespace.ts

@@ -28,6 +28,13 @@ import {
 } from '../../resources/internal';
 
 export class Billing implements BillingNamespace {
+  static readonly #pathRoot = '/commerce';
+  static path(subPath: string, param?: { orgId?: string }): string {
+    const { orgId } = param || {};
+    const prefix = orgId ? `/organizations/${orgId}` : '/me';
+    return `${prefix}${Billing.#pathRoot}${subPath}`;
+  }
+
   getPlans = async (params?: GetPlansParams): Promise<ClerkPaginatedResponse<BillingPlanResource>> => {
     const { for: forParam, ...safeParams } = params || {};
     const searchParams = { ...safeParams, payer_type: forParam === 'organization' ? 'org' : 'user' };

packages/clerk-js/src/core/modules/billing/payment-source-methods.ts

@@ -1,55 +1,56 @@
 import type {
-  AddPaymentSourceParams,
-  BillingInitializedPaymentSourceJSON,
-  BillingPaymentSourceJSON,
+  AddPaymentMethodParams,
+  BillingInitializedPaymentMethodJSON,
+  BillingPaymentMethodJSON,
   ClerkPaginatedResponse,
-  GetPaymentSourcesParams,
-  InitializePaymentSourceParams,
+  GetPaymentMethodsParams,
+  InitializePaymentMethodParams,
 } from '@clerk/types';
 
 import { convertPageToOffsetSearchParams } from '../../../utils/convertPageToOffsetSearchParams';
-import { BaseResource, BillingInitializedPaymentSource, BillingPaymentSource } from '../../resources/internal';
+import { BaseResource, BillingInitializedPaymentMethod, BillingPaymentMethod } from '../../resources/internal';
+import { Billing } from './namespace';
 
-export const initializePaymentSource = async (params: InitializePaymentSourceParams) => {
+const PAYMENT_METHODS_PATH = '/payment_methods';
+
+export const initializePaymentMethod = async (params: InitializePaymentMethodParams) => {
   const { orgId, ...rest } = params;
   const json = (
     await BaseResource._fetch({
-      path: orgId
-        ? `/organizations/${orgId}/commerce/payment_sources/initialize`
-        : `/me/commerce/payment_sources/initialize`,
+      path: Billing.path(`${PAYMENT_METHODS_PATH}/initialize`, { orgId }),
       method: 'POST',
       body: rest as any,
     })
-  )?.response as unknown as BillingInitializedPaymentSourceJSON;
-  return new BillingInitializedPaymentSource(json);
+  )?.response as unknown as BillingInitializedPaymentMethodJSON;
+  return new BillingInitializedPaymentMethod(json);
 };
 
-export const addPaymentSource = async (params: AddPaymentSourceParams) => {
+export const addPaymentMethod = async (params: AddPaymentMethodParams) => {
   const { orgId, ...rest } = params;
 
   const json = (
     await BaseResource._fetch({
-      path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+      path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
       method: 'POST',
       body: rest as any,
     })
-  )?.response as unknown as BillingPaymentSourceJSON;
-  return new BillingPaymentSource(json);
+  )?.response as unknown as BillingPaymentMethodJSON;
+  return new BillingPaymentMethod(json);
 };
 
-export const getPaymentSources = async (params: GetPaymentSourcesParams) => {
+export const getPaymentMethods = async (params: GetPaymentMethodsParams) => {
   const { orgId, ...rest } = params;
 
   return await BaseResource._fetch({
-    path: orgId ? `/organizations/${orgId}/commerce/payment_sources` : `/me/commerce/payment_sources`,
+    path: Billing.path(PAYMENT_METHODS_PATH, { orgId }),
     method: 'GET',
     search: convertPageToOffsetSearchParams(rest),
   }).then(res => {
     const { data: paymentSources, total_count } =
-      res?.response as unknown as ClerkPaginatedResponse<BillingPaymentSourceJSON>;
+      res?.response as unknown as ClerkPaginatedResponse<BillingPaymentMethodJSON>;
     return {
       total_count,
-      data: paymentSources.map(paymentSource => new BillingPaymentSource(paymentSource)),
+      data: paymentSources.map(paymentMethod => new BillingPaymentMethod(paymentMethod)),
     };
   });
 };

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

@@ -5,6 +5,7 @@ import type {
   BillingCheckoutResource,
   BillingCheckoutTotals,
   BillingPayerResource,
+  BillingPaymentMethodResource,
   BillingSubscriptionPlanPeriod,
   ConfirmCheckoutParams,
 } from '@clerk/types';
@@ -13,13 +14,13 @@ import { unixEpochToDate } from '@/utils/date';
 
 import { billingTotalsFromJSON } from '../../utils';
 import { BillingPayer } from './BillingPayer';
-import { BaseResource, BillingPaymentSource, BillingPlan } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingPlan } from './internal';
 
 export class BillingCheckout extends BaseResource implements BillingCheckoutResource {
   id!: string;
   externalClientSecret!: string;
   externalGatewayId!: string;
-  paymentSource?: BillingPaymentSource;
+  paymentMethod?: BillingPaymentMethodResource;
   plan!: BillingPlan;
   planPeriod!: BillingSubscriptionPlanPeriod;
   planPeriodStart!: number | undefined;
@@ -42,7 +43,7 @@ export class BillingCheckout extends BaseResource implements BillingCheckoutReso
     this.id = data.id;
     this.externalClientSecret = data.external_client_secret;
     this.externalGatewayId = data.external_gateway_id;
-    this.paymentSource = data.payment_source ? new BillingPaymentSource(data.payment_source) : undefined;
+    this.paymentMethod = data.payment_method ? new BillingPaymentMethod(data.payment_method) : undefined;
     this.plan = new BillingPlan(data.plan);
     this.planPeriod = data.plan_period;
     this.planPeriodStart = data.plan_period_start;

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

@@ -2,23 +2,23 @@ import type {
   BillingMoneyAmount,
   BillingPaymentChargeType,
   BillingPaymentJSON,
+  BillingPaymentMethodResource,
   BillingPaymentResource,
-  BillingPaymentSourceResource,
   BillingPaymentStatus,
   BillingSubscriptionItemResource,
 } from '@clerk/types';
 
 import { billingMoneyAmountFromJSON } from '../../utils';
 import { unixEpochToDate } from '../../utils/date';
-import { BaseResource, BillingPaymentSource, BillingSubscriptionItem } from './internal';
+import { BaseResource, BillingPaymentMethod, BillingSubscriptionItem } from './internal';
 
 export class BillingPayment extends BaseResource implements BillingPaymentResource {
   id!: string;
   amount!: BillingMoneyAmount;
   failedAt?: Date;
   paidAt?: Date;
   updatedAt!: Date;
-  paymentSource!: BillingPaymentSourceResource;
+  paymentMethod!: BillingPaymentMethodResource;
   subscriptionItem!: BillingSubscriptionItemResource;
   chargeType!: BillingPaymentChargeType;
   status!: BillingPaymentStatus;
@@ -38,7 +38,7 @@ export class BillingPayment extends BaseResource implements BillingPaymentResour
     this.paidAt = data.paid_at ? unixEpochToDate(data.paid_at) : undefined;
     this.failedAt = data.failed_at ? unixEpochToDate(data.failed_at) : undefined;
     this.updatedAt = unixEpochToDate(data.updated_at);
-    this.paymentSource = new BillingPaymentSource(data.payment_source);
+    this.paymentMethod = new BillingPaymentMethod(data.payment_method);
     this.subscriptionItem = new BillingSubscriptionItem(data.subscription_item);
     this.chargeType = data.charge_type;
     this.status = data.status;

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

@@ -1,32 +1,32 @@
 import type {
-  BillingInitializedPaymentSourceJSON,
-  BillingInitializedPaymentSourceResource,
-  BillingPaymentSourceJSON,
-  BillingPaymentSourceResource,
-  BillingPaymentSourceStatus,
+  BillingInitializedPaymentMethodJSON,
+  BillingInitializedPaymentMethodResource,
+  BillingPaymentMethodJSON,
+  BillingPaymentMethodResource,
+  BillingPaymentMethodStatus,
   DeletedObjectJSON,
   MakeDefaultPaymentSourceParams,
   RemovePaymentSourceParams,
 } from '@clerk/types';
 
 import { BaseResource, DeletedObject } from './internal';
 
-export class BillingPaymentSource extends BaseResource implements BillingPaymentSourceResource {
+export class BillingPaymentMethod extends BaseResource implements BillingPaymentMethodResource {
   id!: string;
   last4!: string;
   paymentMethod!: string;
   cardType!: string;
   isDefault!: boolean;
   isRemovable!: boolean;
-  status!: BillingPaymentSourceStatus;
+  status!: BillingPaymentMethodStatus;
   walletType: string | undefined;
 
-  constructor(data: BillingPaymentSourceJSON) {
+  constructor(data: BillingPaymentMethodJSON) {
     super();
     this.fromJSON(data);
   }
 
-  protected fromJSON(data: BillingPaymentSourceJSON | null): this {
+  protected fromJSON(data: BillingPaymentMethodJSON | null): this {
     if (!data) {
       return this;
     }
@@ -71,17 +71,17 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
   }
 }
 
-export class BillingInitializedPaymentSource extends BaseResource implements BillingInitializedPaymentSourceResource {
+export class BillingInitializedPaymentMethod extends BaseResource implements BillingInitializedPaymentMethodResource {
   externalClientSecret!: string;
   externalGatewayId!: string;
   paymentMethodOrder!: string[];
 
-  constructor(data: BillingInitializedPaymentSourceJSON) {
+  constructor(data: BillingInitializedPaymentMethodJSON) {
     super();
     this.fromJSON(data);
   }
 
-  protected fromJSON(data: BillingInitializedPaymentSourceJSON | null): this {
+  protected fromJSON(data: BillingInitializedPaymentMethodJSON | null): this {
     if (!data) {
       return this;
     }

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

@@ -59,7 +59,7 @@ export class BillingSubscription extends BaseResource implements BillingSubscrip
 
 export class BillingSubscriptionItem extends BaseResource implements BillingSubscriptionItemResource {
   id!: string;
-  paymentSourceId!: string;
+  paymentMethodId!: string;
   plan!: BillingPlan;
   planPeriod!: BillingSubscriptionPlanPeriod;
   status!: BillingSubscriptionStatus;
@@ -86,7 +86,7 @@ export class BillingSubscriptionItem extends BaseResource implements BillingSubs
     }
 
     this.id = data.id;
-    this.paymentSourceId = data.payment_source_id;
+    this.paymentMethodId = data.payment_method_id;
     this.plan = new BillingPlan(data.plan);
     this.planPeriod = data.plan_period;
     this.status = data.status;

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

@@ -28,7 +28,7 @@ import type {
 
 import { convertPageToOffsetSearchParams } from '../../utils/convertPageToOffsetSearchParams';
 import { unixEpochToDate } from '../../utils/date';
-import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/billing';
+import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '../modules/billing';
 import { BaseResource, OrganizationInvitation, OrganizationMembership } from './internal';
 import { OrganizationDomain } from './OrganizationDomain';
 import { OrganizationMembershipRequest } from './OrganizationMembershipRequest';
@@ -262,22 +262,22 @@ export class Organization extends BaseResource implements OrganizationResource {
     }).then(res => new Organization(res?.response as OrganizationJSON));
   };
 
-  initializePaymentSource: typeof initializePaymentSource = params => {
-    return initializePaymentSource({
+  initializePaymentMethod: typeof initializePaymentMethod = params => {
+    return initializePaymentMethod({
       ...params,
       orgId: this.id,
     });
   };
 
-  addPaymentSource: typeof addPaymentSource = params => {
-    return addPaymentSource({
+  addPaymentMethod: typeof addPaymentMethod = params => {
+    return addPaymentMethod({
       ...params,
       orgId: this.id,
     });
   };
 
-  getPaymentSources: typeof getPaymentSources = params => {
-    return getPaymentSources({
+  getPaymentMethods: typeof getPaymentMethods = params => {
+    return getPaymentMethods({
       ...params,
       orgId: this.id,
     });

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

@@ -36,7 +36,7 @@ import { unixEpochToDate } from '../../utils/date';
 import { normalizeUnsafeMetadata } from '../../utils/resourceParams';
 import { getFullName } from '../../utils/user';
 import { eventBus, events } from '../events';
-import { addPaymentSource, getPaymentSources, initializePaymentSource } from '../modules/billing';
+import { addPaymentMethod, getPaymentMethods, initializePaymentMethod } from '../modules/billing';
 import { BackupCode } from './BackupCode';
 import {
   BaseResource,
@@ -291,16 +291,16 @@ export class User extends BaseResource implements UserResource {
     return new DeletedObject(json);
   };
 
-  initializePaymentSource: typeof initializePaymentSource = params => {
-    return initializePaymentSource(params);
+  initializePaymentMethod: typeof initializePaymentMethod = params => {
+    return initializePaymentMethod(params);
   };
 
-  addPaymentSource: typeof addPaymentSource = params => {
-    return addPaymentSource(params);
+  addPaymentMethod: typeof addPaymentMethod = params => {
+    return addPaymentMethod(params);
   };
 
-  getPaymentSources: typeof getPaymentSources = params => {
-    return getPaymentSources(params);
+  getPaymentMethods: typeof getPaymentMethods = params => {
+    return getPaymentMethods(params);
   };
 
   get verifiedExternalAccounts() {

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

@@ -161,7 +161,7 @@ export const CheckoutComplete = () => {
   const { setIsOpen } = useDrawerContext();
   const { newSubscriptionRedirectUrl } = useCheckoutContext();
   const { checkout } = useCheckout();
-  const { totals, paymentSource, planPeriodStart, freeTrialEndsAt } = checkout;
+  const { totals, paymentMethod, planPeriodStart, freeTrialEndsAt } = checkout;
   const [mousePosition, setMousePosition] = useState({ x: 256, y: 256 });
 
   const prefersReducedMotion = usePrefersReducedMotion();
@@ -438,10 +438,11 @@ export const CheckoutComplete = () => {
             <LineItems.Description
               text={
                 totals.totalDueNow.amount > 0 || freeTrialEndsAt !== null
-                  ? paymentSource
-                    ? paymentSource.paymentMethod !== 'card'
-                      ? `${capitalize(paymentSource.paymentMethod)}`
-                      : `${capitalize(paymentSource.cardType)} ⋯ ${paymentSource.last4}`
+                  ? paymentMethod
+                    ? // is this the right place?
+                      paymentMethod.paymentMethod !== 'card'
+                      ? `${capitalize(paymentMethod.paymentMethod)}`
+                      : `${capitalize(paymentMethod.cardType)} ⋯ ${paymentMethod.last4}`
                     : '–'
                   : planPeriodStart
                     ? formatDate(new Date(planPeriodStart))

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

@@ -1,5 +1,5 @@
 import { __experimental_useCheckout as useCheckout } from '@clerk/shared/react';
-import type { BillingMoneyAmount, BillingPaymentSourceResource, ConfirmCheckoutParams } from '@clerk/types';
+import type { BillingMoneyAmount, BillingPaymentMethodResource, ConfirmCheckoutParams } from '@clerk/types';
 import { useMemo, useState } from 'react';
 
 import { Card } from '@/ui/elements/Card';
@@ -367,16 +367,16 @@ const ExistingPaymentSourceForm = withCardStateProvider(
     paymentSources,
   }: {
     totalDueNow: BillingMoneyAmount;
-    paymentSources: BillingPaymentSourceResource[];
+    paymentSources: BillingPaymentMethodResource[];
   }) => {
     const submitLabel = useSubmitLabel();
     const { checkout } = useCheckout();
-    const { paymentSource, isImmediatePlanChange, freeTrialEndsAt } = checkout;
+    const { paymentMethod, isImmediatePlanChange, freeTrialEndsAt } = checkout;
 
     const { payWithExistingPaymentSource } = useCheckoutMutations();
     const card = useCardState();
-    const [selectedPaymentSource, setSelectedPaymentSource] = useState<BillingPaymentSourceResource | undefined>(
-      paymentSource || paymentSources.find(p => p.isDefault),
+    const [selectedPaymentSource, setSelectedPaymentSource] = useState<BillingPaymentMethodResource | undefined>(
+      paymentMethod || paymentSources.find(p => p.isDefault),
     );
 
     const options = useMemo(() => {

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

@@ -1,9 +1,9 @@
-import type { BillingPaymentSourceResource } from '@clerk/types';
+import type { BillingPaymentMethodResource } from '@clerk/types';
 
 import { Badge, descriptors, Flex, Icon, localizationKeys, Text } from '../../customizables';
 import { CreditCard, GenericPayment } from '../../icons';
 
-export const PaymentSourceRow = ({ paymentSource }: { paymentSource: BillingPaymentSourceResource }) => {
+export const PaymentSourceRow = ({ paymentSource }: { paymentSource: BillingPaymentMethodResource }) => {
   return (
     <Flex
       sx={{ overflow: 'hidden' }}