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

Author: panteliselef

.changeset/rich-breads-move.md

@@ -0,0 +1,16 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': patch
+'@clerk/types': minor
+---
+
+[Billing Beta] Rename payment source to payment method.
+
+`Clerk.user.initializePaymentSource()` -> `Clerk.user.initializePaymentMethod()`
+`Clerk.user.addPaymentSource()` -> `Clerk.user.addPaymentMethod()`
+`Clerk.user.getPaymentSources()` -> `Clerk.user.getPaymentMethods()`
+
+`Clerk.organization.initializePaymentSource()` -> `Clerk.organization.initializePaymentMethod()`
+`Clerk.organization.addPaymentSource()` -> `Clerk.organization.addPaymentMethod()`
+`Clerk.organization.getPaymentSources()` -> `Clerk.organization.getPaymentMethods()`
+

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

@@ -5,26 +5,26 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/act-claim.mdx",
   "types/act-jwt-claim.mdx",
   "types/active-session-resource.mdx",
-  "types/add-payment-source-params.mdx",
+  "types/add-payment-method-params.mdx",
   "types/billing-checkout-json.mdx",
   "types/billing-checkout-resource.mdx",
   "types/billing-checkout-totals-json.mdx",
   "types/billing-checkout-totals.mdx",
-  "types/billing-initialized-payment-source-json.mdx",
-  "types/billing-initialized-payment-source-resource.mdx",
+  "types/billing-initialized-payment-method-json.mdx",
+  "types/billing-initialized-payment-method-resource.mdx",
   "types/billing-money-amount-json.mdx",
   "types/billing-money-amount.mdx",
   "types/billing-namespace.mdx",
   "types/billing-payer-json.mdx",
+  "types/billing-payer-methods.mdx",
   "types/billing-payer-resource-type.mdx",
   "types/billing-payer-resource.mdx",
   "types/billing-payment-charge-type.mdx",
   "types/billing-payment-json.mdx",
+  "types/billing-payment-method-json.mdx",
+  "types/billing-payment-method-resource.mdx",
+  "types/billing-payment-method-status.mdx",
   "types/billing-payment-resource.mdx",
-  "types/billing-payment-source-json.mdx",
-  "types/billing-payment-source-methods.mdx",
-  "types/billing-payment-source-resource.mdx",
-  "types/billing-payment-source-status.mdx",
   "types/billing-payment-status.mdx",
   "types/billing-plan-json.mdx",
   "types/billing-plan-resource.mdx",
@@ -72,21 +72,21 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/field-errors.mdx",
   "types/for-payer-type.mdx",
   "types/get-payment-attempts-params.mdx",
-  "types/get-payment-sources-params.mdx",
+  "types/get-payment-methods-params.mdx",
   "types/get-plans-params.mdx",
   "types/get-statements-params.mdx",
   "types/get-subscription-params.mdx",
   "types/get-token.mdx",
   "types/id-selectors.mdx",
-  "types/initialize-payment-source-params.mdx",
+  "types/initialize-payment-method-params.mdx",
   "types/internal_checkout-props.mdx",
   "types/internal_plan-details-props.mdx",
   "types/internal_subscription-details-props.mdx",
   "types/jwt-claims.mdx",
   "types/jwt-header.mdx",
   "types/legacy-redirect-props.mdx",
   "types/localization-resource.mdx",
-  "types/make-default-payment-source-params.mdx",
+  "types/make-default-payment-method-params.mdx",
   "types/multi-domain-and-or-proxy.mdx",
   "types/organization-custom-role-key.mdx",
   "types/organization-domain-resource.mdx",
@@ -109,7 +109,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/protect-props.mdx",
   "types/record-to-path.mdx",
   "types/redirect-options.mdx",
-  "types/remove-payment-source-params.mdx",
+  "types/remove-payment-method-params.mdx",
   "types/reverification-config.mdx",
   "types/saml-strategy.mdx",
   "types/sdk-metadata.mdx",

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,39 +1,39 @@
 import type {
-  BillingInitializedPaymentSourceJSON,
-  BillingInitializedPaymentSourceResource,
-  BillingPaymentSourceJSON,
-  BillingPaymentSourceResource,
-  BillingPaymentSourceStatus,
+  BillingInitializedPaymentMethodJSON,
+  BillingInitializedPaymentMethodResource,
+  BillingPaymentMethodJSON,
+  BillingPaymentMethodResource,
+  BillingPaymentMethodStatus,
   DeletedObjectJSON,
-  MakeDefaultPaymentSourceParams,
-  RemovePaymentSourceParams,
+  MakeDefaultPaymentMethodParams,
+  RemovePaymentMethodParams,
 } 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;
+  paymentType!: 'card' | 'link';
   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;
     }
 
     this.id = data.id;
     this.last4 = data.last4;
-    this.paymentMethod = data.payment_method;
+    this.paymentType = data.payment_type;
     this.cardType = data.card_type;
     this.isDefault = data.is_default;
     this.isRemovable = data.is_removable;
@@ -43,7 +43,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
     return this;
   }
 
-  public async remove(params?: RemovePaymentSourceParams) {
+  public async remove(params?: RemovePaymentMethodParams) {
     const { orgId } = params ?? {};
     const json = (
       await BaseResource._fetch({
@@ -57,7 +57,7 @@ export class BillingPaymentSource extends BaseResource implements BillingPayment
     return new DeletedObject(json);
   }
 
-  public async makeDefault(params?: MakeDefaultPaymentSourceParams) {
+  public async makeDefault(params?: MakeDefaultPaymentMethodParams) {
     const { orgId } = params ?? {};
     await BaseResource._fetch({
       path: orgId
@@ -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,
     });