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,
+ };
+}