chore(shared): Add stable keys registry for billing and paginated hooks (#7248)

panteliselef · web-flow · commit 66fdeb46b8ae · 2025-11-18T18:51:12.000+02:00
diff --git a/.changeset/flat-grapes-visit.md b/.changeset/flat-grapes-visit.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/shared/src/react/hooks/__tests__/createBillingPaginatedHook.spec.tsx b/packages/shared/src/react/hooks/__tests__/createBillingPaginatedHook.spec.tsx
@@ -2,6 +2,7 @@ import { act, renderHook, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { ClerkResource } from '../../../types';
+import type { ResourceCacheStableKey } from '../../stable-keys';
 import { createBillingPaginatedHook } from '../createBillingPaginatedHook';
 import { createMockClerk, createMockOrganization, createMockQueryClient, createMockUser } from './mocks/clerk';
 import { wrapper } from './wrapper';
@@ -33,13 +34,13 @@ const useFetcherMock = vi.fn(() => fetcherMock);
 
 const useDummyAuth = createBillingPaginatedHook<DummyResource, DummyParams>({
   hookName: 'useDummyAuth',
-  resourceType: 'dummy',
+  resourceType: 'dummy' as ResourceCacheStableKey,
   useFetcher: useFetcherMock,
 });
 
 const useDummyUnauth = createBillingPaginatedHook<DummyResource, DummyParams>({
   hookName: 'useDummyUnauth',
-  resourceType: 'dummy',
+  resourceType: 'dummy' as ResourceCacheStableKey,
   useFetcher: useFetcherMock,
   options: { unauthenticated: true },
 });
diff --git a/packages/shared/src/react/hooks/__tests__/usePagesOrInfinite.spec.ts b/packages/shared/src/react/hooks/__tests__/usePagesOrInfinite.spec.ts
@@ -2,6 +2,7 @@ import { act, renderHook, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { createDeferredPromise } from '../../../utils/createDeferredPromise';
+import type { ResourceCacheStableKey } from '../../stable-keys';
 import { createCacheKeys } from '../createCacheKeys';
 import { usePagesOrInfinite } from '../usePagesOrInfinite';
 import { createMockClerk, createMockQueryClient } from './mocks/clerk';
@@ -43,7 +44,11 @@ const buildKeys = <Params extends Record<string, unknown>>(
   authenticated = true,
 ) =>
   createCacheKeys({
-    stablePrefix,
+    // Casting to ResourceCacheStableKey to satisfy the type checker,
+    // it is fine because we only want to limit the types to ensure our stable keys
+    // do not diverge when consumed from other pacakges.
+    // Since this is a test mocking most things we can safely ignore the type checker.
+    stablePrefix: stablePrefix as ResourceCacheStableKey,
     authenticated,
     tracked,
     untracked: { args: params },
diff --git a/packages/shared/src/react/hooks/createBillingPaginatedHook.tsx b/packages/shared/src/react/hooks/createBillingPaginatedHook.tsx
@@ -6,6 +6,7 @@ import {
   useOrganizationContext,
   useUserContext,
 } from '../contexts';
+import type { ResourceCacheStableKey } from '../stable-keys';
 import type { PagesOrInfiniteOptions, PaginatedHookConfig, PaginatedResources } from '../types';
 import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
@@ -15,7 +16,7 @@ import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
  */
 type BillingHookConfig<TResource extends ClerkResource, TParams extends PagesOrInfiniteOptions> = {
   hookName: string;
-  resourceType: string;
+  resourceType: ResourceCacheStableKey;
   useFetcher: (
     param: ForPayerType,
   ) => ((params: TParams & { orgId?: string }) => Promise<ClerkPaginatedResponse<TResource>>) | undefined;
diff --git a/packages/shared/src/react/hooks/createCacheKeys.ts b/packages/shared/src/react/hooks/createCacheKeys.ts
@@ -1,13 +1,14 @@
+import type { ResourceCacheStableKey } from '../stable-keys';
+
 /**
  * @internal
  */
 export function createCacheKeys<
   Params,
-  StableKey extends string,
   T extends Record<string, unknown> = Record<string, unknown>,
   U extends Record<string, unknown> | undefined = undefined,
 >(params: {
-  stablePrefix: StableKey;
+  stablePrefix: ResourceCacheStableKey;
   authenticated: boolean;
   tracked: T;
   untracked: U extends { args: Params } ? U : never;
diff --git a/packages/shared/src/react/hooks/useAPIKeys.ts b/packages/shared/src/react/hooks/useAPIKeys.ts
@@ -3,6 +3,7 @@
 import { eventMethodCalled } from '../../telemetry/events/method-called';
 import type { APIKeyResource, GetAPIKeysParams } from '../../types';
 import { useAssertWrappedByClerkProvider, useClerkInstanceContext } from '../contexts';
+import { STABLE_KEYS } from '../stable-keys';
 import type { PaginatedHookConfig, PaginatedResources } from '../types';
 import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
@@ -104,7 +105,7 @@ export function useAPIKeys<T extends UseAPIKeysParams>(params?: T): UseAPIKeysRe
       pageSize: safeValues.pageSize,
     },
     keys: createCacheKeys({
-      stablePrefix: 'apiKeys',
+      stablePrefix: STABLE_KEYS.API_KEYS_KEY,
       authenticated: Boolean(clerk.user),
       tracked: {
         subject: safeValues.subject,
diff --git a/packages/shared/src/react/hooks/useOrganization.tsx b/packages/shared/src/react/hooks/useOrganization.tsx
@@ -17,6 +17,7 @@ import {
   useOrganizationContext,
   useSessionContext,
 } from '../contexts';
+import { STABLE_KEYS } from '../stable-keys';
 import type { PaginatedHookConfig, PaginatedResources, PaginatedResourcesWithDefault } from '../types';
 import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
@@ -368,7 +369,7 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
       pageSize: domainSafeValues.pageSize,
     },
     keys: createCacheKeys({
-      stablePrefix: 'domains',
+      stablePrefix: STABLE_KEYS.DOMAINS_KEY,
       authenticated: Boolean(organization),
       tracked: {
         organizationId: organization?.id,
@@ -390,7 +391,7 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
       pageSize: membershipRequestSafeValues.pageSize,
     },
     keys: createCacheKeys({
-      stablePrefix: 'membershipRequests',
+      stablePrefix: STABLE_KEYS.MEMBERSHIP_REQUESTS_KEY,
       authenticated: Boolean(organization),
       tracked: {
         organizationId: organization?.id,
@@ -412,7 +413,7 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
       pageSize: membersSafeValues.pageSize,
     },
     keys: createCacheKeys({
-      stablePrefix: 'members',
+      stablePrefix: STABLE_KEYS.MEMBERSHIPS_KEY,
       authenticated: Boolean(organization),
       tracked: {
         organizationId: organization?.id,
@@ -434,7 +435,7 @@ export function useOrganization<T extends UseOrganizationParams>(params?: T): Us
       pageSize: invitationsSafeValues.pageSize,
     },
     keys: createCacheKeys({
-      stablePrefix: 'invitations',
+      stablePrefix: STABLE_KEYS.INVITATIONS_KEY,
       authenticated: Boolean(organization),
       tracked: {
         organizationId: organization?.id,
diff --git a/packages/shared/src/react/hooks/useOrganizationList.tsx b/packages/shared/src/react/hooks/useOrganizationList.tsx
@@ -11,6 +11,7 @@ import type {
   UserOrganizationInvitationResource,
 } from '../../types';
 import { useAssertWrappedByClerkProvider, useClerkInstanceContext, useUserContext } from '../contexts';
+import { STABLE_KEYS } from '../stable-keys';
 import type { PaginatedHookConfig, PaginatedResources, PaginatedResourcesWithDefault } from '../types';
 import { createCacheKeys } from './createCacheKeys';
 import { usePagesOrInfinite, useWithSafeValues } from './usePagesOrInfinite';
@@ -318,7 +319,7 @@ export function useOrganizationList<T extends UseOrganizationListParams>(params?
       pageSize: userMembershipsSafeValues.pageSize,
     },
     keys: createCacheKeys({
-      stablePrefix: 'userMemberships',
+      stablePrefix: STABLE_KEYS.USER_MEMBERSHIPS_KEY,
       authenticated: Boolean(user),
       tracked: {
         userId: user?.id,
@@ -341,7 +342,7 @@ export function useOrganizationList<T extends UseOrganizationListParams>(params?
       pageSize: userInvitationsSafeValues.pageSize,
     },
     keys: createCacheKeys({
-      stablePrefix: 'userInvitations',
+      stablePrefix: STABLE_KEYS.USER_INVITATIONS_KEY,
       authenticated: Boolean(user),
       tracked: {
         userId: user?.id,
@@ -363,7 +364,7 @@ export function useOrganizationList<T extends UseOrganizationListParams>(params?
       pageSize: userSuggestionsSafeValues.pageSize,
     },
     keys: createCacheKeys({
-      stablePrefix: 'userSuggestions',
+      stablePrefix: STABLE_KEYS.USER_SUGGESTIONS_KEY,
       authenticated: Boolean(user),
       tracked: {
         userId: user?.id,
diff --git a/packages/shared/src/react/hooks/usePaymentAttempts.tsx b/packages/shared/src/react/hooks/usePaymentAttempts.tsx
@@ -1,13 +1,14 @@
 import type { BillingPaymentResource, GetPaymentAttemptsParams } from '../../types';
 import { useClerkInstanceContext } from '../contexts';
+import { STABLE_KEYS } from '../stable-keys';
 import { createBillingPaginatedHook } from './createBillingPaginatedHook';
 
 /**
  * @internal
  */
 export const usePaymentAttempts = createBillingPaginatedHook<BillingPaymentResource, GetPaymentAttemptsParams>({
   hookName: 'usePaymentAttempts',
-  resourceType: 'billing-payment-attempts',
+  resourceType: STABLE_KEYS.PAYMENT_ATTEMPTS_KEY,
   useFetcher: () => {
     const clerk = useClerkInstanceContext();
     if (clerk.loaded) {
diff --git a/packages/shared/src/react/hooks/usePaymentMethods.tsx b/packages/shared/src/react/hooks/usePaymentMethods.tsx
@@ -1,13 +1,14 @@
 import type { BillingPaymentMethodResource, GetPaymentMethodsParams } from '../../types';
 import { useOrganizationContext, useUserContext } from '../contexts';
+import { STABLE_KEYS } from '../stable-keys';
 import { createBillingPaginatedHook } from './createBillingPaginatedHook';
 
 /**
  * @internal
  */
 export const usePaymentMethods = createBillingPaginatedHook<BillingPaymentMethodResource, GetPaymentMethodsParams>({
   hookName: 'usePaymentMethods',
-  resourceType: 'commerce-payment-methods',
+  resourceType: STABLE_KEYS.PAYMENT_METHODS_KEY,
   useFetcher: resource => {
     const { organization } = useOrganizationContext();
     const user = useUserContext();
diff --git a/packages/shared/src/react/hooks/usePlans.tsx b/packages/shared/src/react/hooks/usePlans.tsx
@@ -1,13 +1,14 @@
 import type { BillingPlanResource, GetPlansParams } from '../../types';
 import { useClerkInstanceContext } from '../contexts';
+import { STABLE_KEYS } from '../stable-keys';
 import { createBillingPaginatedHook } from './createBillingPaginatedHook';
 
 /**
  * @internal
  */
 export const usePlans = createBillingPaginatedHook<BillingPlanResource, GetPlansParams>({
   hookName: 'usePlans',
-  resourceType: 'billing-plans',
+  resourceType: STABLE_KEYS.PLANS_KEY,
   useFetcher: _for => {
     const clerk = useClerkInstanceContext();
     if (!clerk.loaded) {
diff --git a/packages/shared/src/react/hooks/useStatements.tsx b/packages/shared/src/react/hooks/useStatements.tsx
@@ -1,13 +1,14 @@
 import type { BillingStatementResource, GetStatementsParams } from '../../types';
 import { useClerkInstanceContext } from '../contexts';
+import { STABLE_KEYS } from '../stable-keys';
 import { createBillingPaginatedHook } from './createBillingPaginatedHook';
 
 /**
  * @internal
  */
 export const useStatements = createBillingPaginatedHook<BillingStatementResource, GetStatementsParams>({
   hookName: 'useStatements',
-  resourceType: 'billing-statements',
+  resourceType: STABLE_KEYS.STATEMENTS_KEY,
   useFetcher: () => {
     const clerk = useClerkInstanceContext();
     if (clerk.loaded) {
diff --git a/packages/shared/src/react/hooks/useSubscription.rq.tsx b/packages/shared/src/react/hooks/useSubscription.rq.tsx
@@ -10,6 +10,7 @@ import {
   useOrganizationContext,
   useUserContext,
 } from '../contexts';
+import { STABLE_KEYS } from '../stable-keys';
 import type { SubscriptionResult, UseSubscriptionParams } from './useSubscription.types';
 
 const HOOK_NAME = 'useSubscription';
@@ -25,7 +26,7 @@ export const subscriptionQuery = <T extends Record<string, unknown>, U extends R
   trackedKeys: T;
   untrackedKeys?: U;
 }) => {
-  const stableKey = 'commerce-subscription';
+  const stableKey = STABLE_KEYS.SUBSCRIPTION_KEY;
   const { trackedKeys, untrackedKeys } = params;
   return {
     queryKey: [stableKey, trackedKeys, untrackedKeys] as const,
diff --git a/packages/shared/src/react/hooks/useSubscription.swr.tsx b/packages/shared/src/react/hooks/useSubscription.swr.tsx
@@ -9,6 +9,7 @@ import {
   useOrganizationContext,
   useUserContext,
 } from '../contexts';
+import { STABLE_KEYS } from '../stable-keys';
 import type { SubscriptionResult, UseSubscriptionParams } from './useSubscription.types';
 
 const hookName = 'useSubscription';
@@ -40,7 +41,7 @@ export function useSubscription(params?: UseSubscriptionParams): SubscriptionRes
   const swr = useSWR(
     isEnabled
       ? {
-          type: 'commerce-subscription',
+          type: STABLE_KEYS.SUBSCRIPTION_KEY,
           userId: user?.id,
           args: { orgId: isOrganization ? organization?.id : undefined },
         }
diff --git a/packages/shared/src/react/stable-keys.ts b/packages/shared/src/react/stable-keys.ts
@@ -0,0 +1,53 @@
+// Keys for `useOrganizationList`
+const USER_MEMBERSHIPS_KEY = 'userMemberships';
+const USER_INVITATIONS_KEY = 'userInvitations';
+const USER_SUGGESTIONS_KEY = 'userSuggestions';
+
+// Keys for `useOrganization`
+const DOMAINS_KEY = 'domains';
+const MEMBERSHIP_REQUESTS_KEY = 'membershipRequests';
+const MEMBERSHIPS_KEY = 'memberships';
+const INVITATIONS_KEY = 'invitations';
+
+// Keys for `useAPIKeys`
+const API_KEYS_KEY = 'apiKeys';
+
+// Keys for `usePlans`
+const PLANS_KEY = 'billing-plans';
+
+// Keys for `useSubscription`
+const SUBSCRIPTION_KEY = 'billing-subscription';
+
+// Keys for `usePaymentMethods`
+const PAYMENT_METHODS_KEY = 'billing-payment-methods';
+
+// Keys for `usePaymentAttempts`
+const PAYMENT_ATTEMPTS_KEY = 'billing-payment-attempts';
+
+// Keys for `useStatements`
+const STATEMENTS_KEY = 'billing-statements';
+
+export const STABLE_KEYS = {
+  // Keys for `useOrganizationList`
+  USER_MEMBERSHIPS_KEY,
+  USER_INVITATIONS_KEY,
+  USER_SUGGESTIONS_KEY,
+
+  // Keys for `useOrganization`
+  DOMAINS_KEY,
+  MEMBERSHIP_REQUESTS_KEY,
+  MEMBERSHIPS_KEY,
+  INVITATIONS_KEY,
+
+  // Keys for billing
+  PLANS_KEY,
+  SUBSCRIPTION_KEY,
+  PAYMENT_METHODS_KEY,
+  PAYMENT_ATTEMPTS_KEY,
+  STATEMENTS_KEY,
+
+  // Keys for `useAPIKeys`
+  API_KEYS_KEY,
+} as const;
+
+export type ResourceCacheStableKey = (typeof STABLE_KEYS)[keyof typeof STABLE_KEYS];
