feat(clerk-js, localizations, ui): Add credits information in the user/org profile

.changeset/fancy-rats-stick.md

@@ -0,0 +1,8 @@
+---
+'@clerk/localizations': minor
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+'@clerk/ui': minor
+---
+
+Add account credits section and credit history page to the billing tab for payers with an existing credit balance.

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

@@ -1,5 +1,9 @@
 import type {
   BillingCheckoutJSON,
+  BillingCreditBalanceJSON,
+  BillingCreditBalanceResource,
+  BillingCreditLedgerJSON,
+  BillingCreditLedgerResource,
   BillingNamespace,
   BillingPaymentJSON,
   BillingPaymentResource,
@@ -11,6 +15,8 @@ import type {
   BillingSubscriptionResource,
   ClerkPaginatedResponse,
   CreateCheckoutParams,
+  GetCreditBalanceParams,
+  GetCreditHistoryParams,
   GetPaymentAttemptsParams,
   GetPlansParams,
   GetStatementsParams,
@@ -21,6 +27,8 @@ import { convertPageToOffsetSearchParams } from '../../../utils/convertPageToOff
 import {
   BaseResource,
   BillingCheckout,
+  BillingCreditBalance,
+  BillingCreditLedger,
   BillingPayment,
   BillingPlan,
   BillingStatement,
@@ -140,4 +148,29 @@ export class Billing implements BillingNamespace {
 
     return new BillingCheckout(json);
   };
+
+  getCreditBalance = async (params: GetCreditBalanceParams): Promise<BillingCreditBalanceResource> => {
+    return await BaseResource._fetch({
+      path: Billing.path('/credits', { orgId: params.orgId }),
+      method: 'GET',
+    }).then(res => new BillingCreditBalance(res?.response as unknown as BillingCreditBalanceJSON));
+  };
+
+  getCreditHistory = async (
+    params: GetCreditHistoryParams,
+  ): Promise<ClerkPaginatedResponse<BillingCreditLedgerResource>> => {
+    return await BaseResource._fetch({
+      path: Billing.path('/credits/history', { orgId: params.orgId }),
+      method: 'GET',
+    }).then(res => {
+      const { data, total_count } = res?.response as unknown as {
+        data: BillingCreditLedgerJSON[];
+        total_count: number;
+      };
+      return {
+        total_count,
+        data: data.map(item => new BillingCreditLedger(item)),
+      };
+    });
+  };
 }

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

@@ -0,0 +1,11 @@
+import type { BillingCreditBalanceJSON, BillingCreditBalanceResource, BillingMoneyAmount } from '@clerk/shared/types';
+
+import { billingMoneyAmountFromJSON } from '../../utils';
+
+export class BillingCreditBalance implements BillingCreditBalanceResource {
+  balance: BillingMoneyAmount | null;
+
+  constructor(data: BillingCreditBalanceJSON) {
+    this.balance = data.balance ? billingMoneyAmountFromJSON(data.balance) : null;
+  }
+}

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

@@ -0,0 +1,32 @@
+import type { BillingCreditLedgerJSON, BillingCreditLedgerResource, BillingMoneyAmount } from '@clerk/shared/types';
+
+import { billingMoneyAmountFromJSON } from '@/utils/billing';
+import { unixEpochToDate } from '@/utils/date';
+
+import { BaseResource } from './internal';
+
+export class BillingCreditLedger extends BaseResource implements BillingCreditLedgerResource {
+  id!: string;
+  amount!: BillingMoneyAmount;
+  sourceType!: string;
+  sourceId!: string;
+  createdAt!: Date;
+
+  constructor(data: BillingCreditLedgerJSON) {
+    super();
+    this.fromJSON(data);
+  }
+
+  protected fromJSON(data: BillingCreditLedgerJSON | null): this {
+    if (!data) {
+      return this;
+    }
+
+    this.id = data.id;
+    this.amount = billingMoneyAmountFromJSON(data.amount);
+    this.sourceType = data.source_type;
+    this.sourceId = data.source_id;
+    this.createdAt = unixEpochToDate(data.created_at);
+    return this;
+  }
+}

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

@@ -5,6 +5,8 @@ export * from './Base';
 export * from './APIKey';
 export * from './AuthConfig';
 export * from './BillingCheckout';
+export * from './BillingCreditBalance';
+export * from './BillingCreditLedger';
 export * from './BillingPayment';
 export * from './BillingPaymentMethod';
 export * from './BillingPlan';

packages/localizations/src/en-US.ts

@@ -903,6 +903,15 @@ export const enUS: LocalizationResource = {
     badge__manualInvitation: 'No automatic enrollment',
     badge__unverified: 'Unverified',
     billingPage: {
+      accountCreditsSection: {
+        title: 'Account credits',
+        viewHistory: 'View credit history',
+      },
+      creditHistoryPage: {
+        title: 'Account credit history',
+        tableHeader__amount: 'Amount',
+        tableHeader__date: 'Date',
+      },
       paymentHistorySection: {
         empty: 'No payment history',
         notFound: 'Payment attempt not found',
@@ -1784,6 +1793,15 @@ export const enUS: LocalizationResource = {
       title__codelist: 'Backup codes',
     },
     billingPage: {
+      accountCreditsSection: {
+        title: 'Account credits',
+        viewHistory: 'View credit history',
+      },
+      creditHistoryPage: {
+        title: 'Account credit history',
+        tableHeader__amount: 'Amount',
+        tableHeader__date: 'Date',
+      },
       paymentHistorySection: {
         empty: 'No payment history',
         notFound: 'Payment attempt not found',

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

@@ -23,13 +23,15 @@ export { usePaymentMethods as __experimental_usePaymentMethods } from './usePaym
 export { usePlans as __experimental_usePlans } from './usePlans';
 export { useSubscription as __experimental_useSubscription } from './useSubscription';
 export { useCheckout as __experimental_useCheckout } from './useCheckout';
+export { __internal_useCreditBalanceQuery } from './useCreditBalance';
 
 /**
  * Internal hooks to be consumed only by `@clerk/clerk-js`.
  * These are not considered part of the public API and their query keys can change without notice.
  *
  * These exist here in order to keep React Query implementations in a centralized place.
  */
+export { __internal_useCreditHistoryQuery } from './useCreditHistory';
 export { __internal_useStatementQuery } from './useStatementQuery';
 export { __internal_usePlanDetailsQuery } from './usePlanDetailsQuery';
 export { __internal_usePaymentAttemptQuery } from './usePaymentAttemptQuery';

packages/shared/src/react/hooks/useCreditBalance.tsx

@@ -0,0 +1,103 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+
+import { eventMethodCalled } from '../../telemetry/events';
+import type { BillingCreditBalanceResource, ForPayerType } from '../../types';
+import { useAssertWrappedByClerkProvider, useClerkInstanceContext } from '../contexts';
+import { defineKeepPreviousDataFn } from '../query/keep-previous-data';
+import { useClerkQueryClient } from '../query/use-clerk-query-client';
+import { useClerkQuery } from '../query/useQuery';
+import { STABLE_KEYS } from '../stable-keys';
+import { useOrganizationBase } from './base/useOrganizationBase';
+import { useUserBase } from './base/useUserBase';
+import { createCacheKeys } from './createCacheKeys';
+import { useBillingIsEnabled } from './useBillingIsEnabled';
+import { useClearQueriesOnSignOut } from './useClearQueriesOnSignOut';
+
+const HOOK_NAME = 'useCreditBalance';
+
+export type UseCreditBalanceParams = {
+  for?: ForPayerType;
+  keepPreviousData?: boolean;
+  enabled?: boolean;
+};
+
+export type CreditBalanceResult = {
+  data: BillingCreditBalanceResource | undefined | null;
+  error: Error | undefined;
+  isLoading: boolean;
+  isFetching: boolean;
+  revalidate: () => Promise<void> | void;
+};
+
+/**
+ * @internal
+ */
+export function __internal_useCreditBalanceQuery(params?: UseCreditBalanceParams): CreditBalanceResult {
+  useAssertWrappedByClerkProvider(HOOK_NAME);
+
+  const clerk = useClerkInstanceContext();
+  const user = useUserBase();
+  const organization = useOrganizationBase();
+
+  const billingEnabled = useBillingIsEnabled(params);
+
+  const recordedRef = useRef(false);
+  useEffect(() => {
+    if (!recordedRef.current && clerk?.telemetry) {
+      clerk.telemetry.record(eventMethodCalled(HOOK_NAME));
+      recordedRef.current = true;
+    }
+  }, [clerk]);
+
+  const keepPreviousData = params?.keepPreviousData ?? false;
+
+  const [queryClient] = useClerkQueryClient();
+
+  const { queryKey, invalidationKey, stableKey, authenticated } = useMemo(() => {
+    const isOrganization = params?.for === 'organization';
+    const safeOrgId = isOrganization ? organization?.id : undefined;
+
+    return createCacheKeys({
+      stablePrefix: STABLE_KEYS.CREDIT_BALANCE_KEY,
+      authenticated: true,
+      tracked: {
+        userId: user?.id,
+        orgId: safeOrgId,
+      },
+      untracked: {
+        args: { orgId: safeOrgId },
+      },
+    });
+  }, [user?.id, organization?.id, params?.for]);
+
+  const queriesEnabled = Boolean(user?.id && billingEnabled && (params?.enabled ?? true));
+  useClearQueriesOnSignOut({
+    isSignedOut: user === null,
+    authenticated,
+    stableKeys: stableKey,
+  });
+
+  const query = useClerkQuery({
+    queryKey,
+    queryFn: ({ queryKey }) => {
+      const obj = queryKey[3];
+      return clerk.billing.getCreditBalance(obj.args);
+    },
+    staleTime: 1_000 * 60,
+    enabled: queriesEnabled,
+    placeholderData: defineKeepPreviousDataFn(keepPreviousData && queriesEnabled),
+  });
+
+  const revalidate = useCallback(
+    () => queryClient.invalidateQueries({ queryKey: invalidationKey }),
+    [queryClient, invalidationKey],
+  );
+
+  return {
+    data: query.data,
+    error: query.error ?? undefined,
+    isLoading: query.isLoading,
+    isFetching: query.isFetching,
+    revalidate,
+  };
+}

packages/shared/src/react/hooks/useCreditHistory.tsx

@@ -0,0 +1,98 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+
+import { eventMethodCalled } from '../../telemetry/events';
+import type { BillingCreditLedgerResource, ClerkPaginatedResponse, ForPayerType } from '../../types';
+import { useAssertWrappedByClerkProvider, useClerkInstanceContext } from '../contexts';
+import { useClerkQueryClient } from '../query/use-clerk-query-client';
+import { useClerkQuery } from '../query/useQuery';
+import { INTERNAL_STABLE_KEYS } from '../stable-keys';
+import { useOrganizationBase } from './base/useOrganizationBase';
+import { useUserBase } from './base/useUserBase';
+import { createCacheKeys } from './createCacheKeys';
+import { useBillingIsEnabled } from './useBillingIsEnabled';
+import { useClearQueriesOnSignOut } from './useClearQueriesOnSignOut';
+
+const HOOK_NAME = 'useCreditHistory';
+
+export type UseCreditHistoryParams = {
+  for?: ForPayerType;
+  enabled?: boolean;
+};
+
+export type CreditHistoryResult = {
+  data: ClerkPaginatedResponse<BillingCreditLedgerResource> | undefined;
+  error: Error | undefined;
+  isLoading: boolean;
+  isFetching: boolean;
+  revalidate: () => Promise<void> | void;
+};
+
+/**
+ * @internal
+ */
+export function __internal_useCreditHistoryQuery(params?: UseCreditHistoryParams): CreditHistoryResult {
+  useAssertWrappedByClerkProvider(HOOK_NAME);
+
+  const clerk = useClerkInstanceContext();
+  const user = useUserBase();
+  const organization = useOrganizationBase();
+
+  const billingEnabled = useBillingIsEnabled(params);
+
+  const recordedRef = useRef(false);
+  useEffect(() => {
+    if (!recordedRef.current && clerk?.telemetry) {
+      clerk.telemetry.record(eventMethodCalled(HOOK_NAME));
+      recordedRef.current = true;
+    }
+  }, [clerk]);
+
+  const [queryClient] = useClerkQueryClient();
+
+  const { queryKey, invalidationKey, stableKey, authenticated } = useMemo(() => {
+    const isOrganization = params?.for === 'organization';
+    const safeOrgId = isOrganization ? organization?.id : undefined;
+
+    return createCacheKeys({
+      stablePrefix: INTERNAL_STABLE_KEYS.CREDIT_HISTORY_KEY,
+      authenticated: true,
+      tracked: {
+        userId: user?.id,
+        orgId: safeOrgId,
+      },
+      untracked: {
+        args: { orgId: safeOrgId },
+      },
+    });
+  }, [user?.id, organization?.id, params?.for]);
+
+  const queriesEnabled = Boolean(user?.id && billingEnabled && (params?.enabled ?? true));
+  useClearQueriesOnSignOut({
+    isSignedOut: user === null,
+    authenticated,
+    stableKeys: stableKey,
+  });
+
+  const query = useClerkQuery({
+    queryKey,
+    queryFn: ({ queryKey }) => {
+      const obj = queryKey[3];
+      return clerk.billing.getCreditHistory(obj.args);
+    },
+    staleTime: 1_000 * 60,
+    enabled: queriesEnabled,
+  });
+
+  const revalidate = useCallback(
+    () => queryClient.invalidateQueries({ queryKey: invalidationKey }),
+    [queryClient, invalidationKey],
+  );
+
+  return {
+    data: query.data,
+    error: query.error ?? undefined,
+    isLoading: query.isLoading,
+    isFetching: query.isFetching,
+    revalidate,
+  };
+}