feat(shared): add internal directory sync react-query hooks

packages/shared/src/react/hooks/__tests__/useOrganizationDirectorySync.spec.tsx

@@ -0,0 +1,92 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ClerkAPIResponseError } from '@/error';
+
+import { INTERNAL_STABLE_KEYS } from '../../stable-keys';
+import { createCacheKeys } from '../createCacheKeys';
+import { __internal_useOrganizationDirectorySync } from '../useOrganizationDirectorySync';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const directory = { id: 'dir_1', enterpriseConnectionId: 'ent_1' };
+const getDirectorySyncSpy = vi.fn((_enterpriseConnectionId: string) => Promise.resolve(directory));
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ queryClient: defaultQueryClient,
+ __internal_lastEmittedResources: {
+ user: null,
+ session: null,
+ organization: { id: 'org_1', getDirectorySync: getDirectorySyncSpy },
+ client: null,
+ },
+});
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const keysFor = (enterpriseConnectionId: string) =>
+ createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_KEY,
+ authenticated: true,
+ tracked: { organizationId: 'org_1', enterpriseConnectionId },
+ untracked: { args: {} },
+ });
+
+const renderDirectorySync = (enterpriseConnectionId: string | null = 'ent_1') =>
+ renderHook(() => __internal_useOrganizationDirectorySync({ enterpriseConnectionId }), { wrapper });
+
+describe('useOrganizationDirectorySync', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('resolves the directory for the connection', async () => {
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ expect(getDirectorySyncSpy).toHaveBeenCalledWith('ent_1');
+ expect(result.current.data).toBe(directory);
+ expect(result.current.error).toBeNull();
+ });
+
+ it('treats a 404 as "no directory yet" and resolves null instead of an error', async () => {
+ getDirectorySyncSpy.mockRejectedValueOnce(new ClerkAPIResponseError('Not found', { status: 404, data: [] }));
+
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ expect(result.current.data).toBeNull();
+ expect(result.current.error).toBeNull();
+ });
+
+ it('stays dormant without an enterprise connection id', () => {
+ const { result } = renderDirectorySync(null);
+
+ expect(getDirectorySyncSpy).not.toHaveBeenCalled();
+ expect(result.current.data).toBeUndefined();
+ });
+
+ it('revalidate refetches only this org+connection, leaving other connections cached', async () => {
+ const { queryKey: otherKey } = keysFor('ent_other');
+ defaultQueryClient.client.setQueryData(otherKey, { id: 'dir_other', enterpriseConnectionId: 'ent_other' });
+
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(getDirectorySyncSpy).toHaveBeenCalledTimes(1);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ expect(getDirectorySyncSpy).toHaveBeenCalledTimes(2);
+ expect(defaultQueryClient.client.getQueryState(otherKey)?.isInvalidated).toBe(false);
+ });
+});

packages/shared/src/react/hooks/__tests__/useOrganizationDirectorySyncUsers.spec.tsx

@@ -0,0 +1,121 @@
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { DirectorySyncResource } from '@/types/directorySync';
+
+import type { UseOrganizationDirectorySyncUsersReturn } from '../useOrganizationDirectorySyncUsers';
+import { __internal_useOrganizationDirectorySyncUsers } from '../useOrganizationDirectorySyncUsers';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const POLL_INTERVAL_MS = 20;
+
+const getUsersSpy = vi.fn(() => Promise.resolve({ data: [{ id: 'du_1' }], total_count: 1 }));
+
+const createDirectory = (id: string) =>
+ ({ id, enterpriseConnectionId: 'ent_1', getUsers: getUsersSpy }) as unknown as DirectorySyncResource;
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ queryClient: defaultQueryClient,
+ __internal_lastEmittedResources: {
+ user: null,
+ session: null,
+ organization: { id: 'org_1' },
+ client: null,
+ },
+});
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const renderUsers = (initialDirectory: DirectorySyncResource | null) =>
+ renderHook(
+ ({ directory }: { directory: DirectorySyncResource | null }) =>
+ __internal_useOrganizationDirectorySyncUsers({ directory, pollIntervalMs: POLL_INTERVAL_MS }),
+ { wrapper, initialProps: { directory: initialDirectory } },
+ );
+
+describe('useOrganizationDirectorySyncUsers', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('stays dormant without a directory', () => {
+ const { result } = renderUsers(null);
+
+ expect(getUsersSpy).not.toHaveBeenCalled();
+ expect(result.current.data).toBeUndefined();
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('polls while armed and stops on stopPolling', async () => {
+ const { result } = renderUsers(createDirectory('dir_1'));
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.isPolling).toBe(false);
+
+ act(() => result.current.startPolling());
+ expect(result.current.isPolling).toBe(true);
+ await waitFor(() => expect(getUsersSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+
+ act(() => result.current.stopPolling());
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('disarms polling when the directory identity changes', async () => {
+ const { result, rerender } = renderUsers(createDirectory('dir_1'));
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ act(() => result.current.startPolling());
+ expect(result.current.isPolling).toBe(true);
+
+ rerender({ directory: createDirectory('dir_2') });
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('keeps polling armed by a child effect in the same commit the directory arrives', async () => {
+ let latest: UseOrganizationDirectorySyncUsersReturn | undefined;
+
+ // Child effects run before parent effects, so this is the ordering a
+ // reset-in-effect implementation would silently cancel.
+ const Child = ({
+ directory,
+ startPolling,
+ }: {
+ directory: DirectorySyncResource | null;
+ startPolling: () => void;
+ }) => {
+ useEffect(() => {
+ if (directory) {
+ startPolling();
+ }
+ }, [directory, startPolling]);
+ return null;
+ };
+
+ const Parent = ({ directory }: { directory: DirectorySyncResource | null }) => {
+ latest = __internal_useOrganizationDirectorySyncUsers({ directory, pollIntervalMs: POLL_INTERVAL_MS });
+ return (
+ <Child
+ directory={directory}
+ startPolling={latest.startPolling}
+ />
+ );
+ };
+
+ const { rerender } = render(<Parent directory={null} />);
+ expect(latest?.isPolling).toBe(false);
+
+ rerender(<Parent directory={createDirectory('dir_1')} />);
+
+ await waitFor(() => expect(latest?.isPolling).toBe(true));
+ await waitFor(() => expect(getUsersSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+ });
+});

packages/shared/src/react/hooks/__tests__/useOrganizationEnterpriseConnectionTestRuns.spec.tsx

@@ -1,10 +1,12 @@
-import { act, renderHook, waitFor } from '@testing-library/react';
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { GetEnterpriseConnectionTestRunsParams } from '@/types/enterpriseConnectionTestRun';
 
 import { INTERNAL_STABLE_KEYS } from '../../stable-keys';
 import { createCacheKeys } from '../createCacheKeys';
+import type { UseOrganizationEnterpriseConnectionTestRunsReturn } from '../useOrganizationEnterpriseConnectionTestRuns';
 import { __internal_useOrganizationEnterpriseConnectionTestRuns } from '../useOrganizationEnterpriseConnectionTestRuns';
 import { createMockClerk, createMockQueryClient } from './mocks/clerk';
 import { wrapper } from './wrapper';
@@ -99,3 +101,69 @@ describe('useOrganizationEnterpriseConnectionTestRuns — revalidate invalidatio
  invalidateSpy.mockRestore();
  });
 });
+
+describe('useOrganizationEnterpriseConnectionTestRuns — polling arm scope', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('keeps polling armed by a child effect in the same commit the connection arrives', async () => {
+ getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+ let latest: UseOrganizationEnterpriseConnectionTestRunsReturn | undefined;
+
+ // Child effects run before parent effects, so this is the ordering a
+ // reset-in-effect implementation would silently cancel.
+ const Child = ({
+ enterpriseConnectionId,
+ revalidate,
+ }: {
+ enterpriseConnectionId: string | null;
+ revalidate: UseOrganizationEnterpriseConnectionTestRunsReturn['revalidate'];
+ }) => {
+ useEffect(() => {
+ if (enterpriseConnectionId) {
+ void revalidate();
+ }
+ }, [enterpriseConnectionId, revalidate]);
+ return null;
+ };
+
+ const Parent = ({ enterpriseConnectionId }: { enterpriseConnectionId: string | null }) => {
+ latest = __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 });
+ return (
+ <Child
+ enterpriseConnectionId={enterpriseConnectionId}
+ revalidate={latest.revalidate}
+ />
+ );
+ };
+
+ const { rerender } = render(<Parent enterpriseConnectionId={null} />);
+ expect(latest?.isPolling).toBe(false);
+
+ rerender(<Parent enterpriseConnectionId='ent_1' />);
+
+ await waitFor(() => expect(latest?.isPolling).toBe(true));
+ await waitFor(() => expect(getTestRunsSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+ });
+
+ it('disarms polling when the connection changes', async () => {
+ getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+ const { result, rerender } = renderHook(
+ ({ enterpriseConnectionId }: { enterpriseConnectionId: string }) =>
+ __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 }),
+ { wrapper, initialProps: { enterpriseConnectionId: 'ent_1' } },
+ );
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+ expect(result.current.isPolling).toBe(true);
+
+ rerender({ enterpriseConnectionId: 'ent_2' });
+ expect(result.current.isPolling).toBe(false);
+ });
+});

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

@@ -49,6 +49,16 @@ export type {
 } from './useOrganizationEnterpriseConnections';
 export { __internal_useOrganizationDomains } from './useOrganizationDomains';
 export type { UseOrganizationDomainsParams, UseOrganizationDomainsReturn } from './useOrganizationDomains';
+export { __internal_useOrganizationDirectorySync } from './useOrganizationDirectorySync';
+export type {
+ UseOrganizationDirectorySyncParams,
+ UseOrganizationDirectorySyncReturn,
+} from './useOrganizationDirectorySync';
+export { __internal_useOrganizationDirectorySyncUsers } from './useOrganizationDirectorySyncUsers';
+export type {
+ UseOrganizationDirectorySyncUsersParams,
+ UseOrganizationDirectorySyncUsersReturn,
+} from './useOrganizationDirectorySyncUsers';
 export { __internal_useOrganizationEnterpriseConnectionTestRuns } from './useOrganizationEnterpriseConnectionTestRuns';
 export type {
  UseOrganizationEnterpriseConnectionTestRunsParams,

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

@@ -0,0 +1,56 @@
+import { useMemo } from 'react';
+
+import type { GetDirectorySyncUsersParams } from '../../types/directorySync';
+import { INTERNAL_STABLE_KEYS } from '../stable-keys';
+import { createCacheKeys } from './createCacheKeys';
+
+/**
+ * @internal
+ */
+export function useOrganizationDirectorySyncCacheKeys(params: {
+ organizationId: string | null;
+ enterpriseConnectionId: string | null;
+}) {
+ const { organizationId, enterpriseConnectionId } = params;
+ return useMemo(() => {
+ return createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_KEY,
+ authenticated: Boolean(organizationId),
+ tracked: {
+ organizationId: organizationId ?? null,
+ enterpriseConnectionId: enterpriseConnectionId ?? null,
+ },
+ untracked: {
+ args: {},
+ },
+ });
+ }, [organizationId, enterpriseConnectionId]);
+}
+
+/**
+ * @internal
+ */
+export function useOrganizationDirectorySyncUsersCacheKeys(params: {
+ organizationId: string | null;
+ enterpriseConnectionId: string | null;
+ directoryId: string | null;
+ args: GetDirectorySyncUsersParams;
+}) {
+ const { organizationId, enterpriseConnectionId, directoryId, args } = params;
+ return useMemo(() => {
+ return createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_USERS_KEY,
+ authenticated: Boolean(organizationId),
+ tracked: {
+ organizationId: organizationId ?? null,
+ enterpriseConnectionId: enterpriseConnectionId ?? null,
+ directoryId: directoryId ?? null,
+ },
+ untracked: {
+ args,
+ },
+ });
+ // The args object is intentionally serialized via the consumer to keep stability.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [organizationId, enterpriseConnectionId, directoryId, JSON.stringify(args)]);
+}

packages/shared/src/react/hooks/__tests__/useOrganizationDirectorySync.spec.tsx

@@ -0,0 +1,92 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ClerkAPIResponseError } from '@/error';
+
+import { INTERNAL_STABLE_KEYS } from '../../stable-keys';
+import { createCacheKeys } from '../createCacheKeys';
+import { __internal_useOrganizationDirectorySync } from '../useOrganizationDirectorySync';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const directory = { id: 'dir_1', enterpriseConnectionId: 'ent_1' };
+const getDirectorySyncSpy = vi.fn((_enterpriseConnectionId: string) => Promise.resolve(directory));
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ queryClient: defaultQueryClient,
+ __internal_lastEmittedResources: {
+ user: null,
+ session: null,
+ organization: { id: 'org_1', getDirectorySync: getDirectorySyncSpy },
+ client: null,
+ },
+});
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const keysFor = (enterpriseConnectionId: string) =>
+ createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_KEY,
+ authenticated: true,
+ tracked: { organizationId: 'org_1', enterpriseConnectionId },
+ untracked: { args: {} },
+ });
+
+const renderDirectorySync = (enterpriseConnectionId: string | null = 'ent_1') =>
+ renderHook(() => __internal_useOrganizationDirectorySync({ enterpriseConnectionId }), { wrapper });
+
+describe('useOrganizationDirectorySync', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('resolves the directory for the connection', async () => {
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ expect(getDirectorySyncSpy).toHaveBeenCalledWith('ent_1');
+ expect(result.current.data).toBe(directory);
+ expect(result.current.error).toBeNull();
+ });
+
+ it('treats a 404 as "no directory yet" and resolves null instead of an error', async () => {
+ getDirectorySyncSpy.mockRejectedValueOnce(new ClerkAPIResponseError('Not found', { status: 404, data: [] }));
+
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ expect(result.current.data).toBeNull();
+ expect(result.current.error).toBeNull();
+ });
+
+ it('stays dormant without an enterprise connection id', () => {
+ const { result } = renderDirectorySync(null);
+
+ expect(getDirectorySyncSpy).not.toHaveBeenCalled();
+ expect(result.current.data).toBeUndefined();
+ });
+
+ it('revalidate refetches only this org+connection, leaving other connections cached', async () => {
+ const { queryKey: otherKey } = keysFor('ent_other');
+ defaultQueryClient.client.setQueryData(otherKey, { id: 'dir_other', enterpriseConnectionId: 'ent_other' });
+
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(getDirectorySyncSpy).toHaveBeenCalledTimes(1);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ expect(getDirectorySyncSpy).toHaveBeenCalledTimes(2);
+ expect(defaultQueryClient.client.getQueryState(otherKey)?.isInvalidated).toBe(false);
+ });
+});

packages/shared/src/react/hooks/__tests__/useOrganizationDirectorySyncUsers.spec.tsx

@@ -0,0 +1,121 @@
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { DirectorySyncResource } from '@/types/directorySync';
+
+import type { UseOrganizationDirectorySyncUsersReturn } from '../useOrganizationDirectorySyncUsers';
+import { __internal_useOrganizationDirectorySyncUsers } from '../useOrganizationDirectorySyncUsers';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const POLL_INTERVAL_MS = 20;
+
+const getUsersSpy = vi.fn(() => Promise.resolve({ data: [{ id: 'du_1' }], total_count: 1 }));
+
+const createDirectory = (id: string) =>
+ ({ id, enterpriseConnectionId: 'ent_1', getUsers: getUsersSpy }) as unknown as DirectorySyncResource;
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ queryClient: defaultQueryClient,
+ __internal_lastEmittedResources: {
+ user: null,
+ session: null,
+ organization: { id: 'org_1' },
+ client: null,
+ },
+});
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const renderUsers = (initialDirectory: DirectorySyncResource | null) =>
+ renderHook(
+ ({ directory }: { directory: DirectorySyncResource | null }) =>
+ __internal_useOrganizationDirectorySyncUsers({ directory, pollIntervalMs: POLL_INTERVAL_MS }),
+ { wrapper, initialProps: { directory: initialDirectory } },
+ );
+
+describe('useOrganizationDirectorySyncUsers', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('stays dormant without a directory', () => {
+ const { result } = renderUsers(null);
+
+ expect(getUsersSpy).not.toHaveBeenCalled();
+ expect(result.current.data).toBeUndefined();
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('polls while armed and stops on stopPolling', async () => {
+ const { result } = renderUsers(createDirectory('dir_1'));
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.isPolling).toBe(false);
+
+ act(() => result.current.startPolling());
+ expect(result.current.isPolling).toBe(true);
+ await waitFor(() => expect(getUsersSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+
+ act(() => result.current.stopPolling());
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('disarms polling when the directory identity changes', async () => {
+ const { result, rerender } = renderUsers(createDirectory('dir_1'));
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ act(() => result.current.startPolling());
+ expect(result.current.isPolling).toBe(true);
+
+ rerender({ directory: createDirectory('dir_2') });
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('keeps polling armed by a child effect in the same commit the directory arrives', async () => {
+ let latest: UseOrganizationDirectorySyncUsersReturn | undefined;
+
+ // Child effects run before parent effects, so this is the ordering a
+ // reset-in-effect implementation would silently cancel.
+ const Child = ({
+ directory,
+ startPolling,
+ }: {
+ directory: DirectorySyncResource | null;
+ startPolling: () => void;
+ }) => {
+ useEffect(() => {
+ if (directory) {
+ startPolling();
+ }
+ }, [directory, startPolling]);
+ return null;
+ };
+
+ const Parent = ({ directory }: { directory: DirectorySyncResource | null }) => {
+ latest = __internal_useOrganizationDirectorySyncUsers({ directory, pollIntervalMs: POLL_INTERVAL_MS });
+ return (
+ <Child
+ directory={directory}
+ startPolling={latest.startPolling}
+ />
+ );
+ };
+
+ const { rerender } = render(<Parent directory={null} />);
+ expect(latest?.isPolling).toBe(false);
+
+ rerender(<Parent directory={createDirectory('dir_1')} />);
+
+ await waitFor(() => expect(latest?.isPolling).toBe(true));
+ await waitFor(() => expect(getUsersSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+ });
+});

packages/shared/src/react/hooks/__tests__/useOrganizationEnterpriseConnectionTestRuns.spec.tsx

@@ -1,10 +1,12 @@
-import { act, renderHook, waitFor } from '@testing-library/react';
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { GetEnterpriseConnectionTestRunsParams } from '@/types/enterpriseConnectionTestRun';
 
 import { INTERNAL_STABLE_KEYS } from '../../stable-keys';
 import { createCacheKeys } from '../createCacheKeys';
+import type { UseOrganizationEnterpriseConnectionTestRunsReturn } from '../useOrganizationEnterpriseConnectionTestRuns';
 import { __internal_useOrganizationEnterpriseConnectionTestRuns } from '../useOrganizationEnterpriseConnectionTestRuns';
 import { createMockClerk, createMockQueryClient } from './mocks/clerk';
 import { wrapper } from './wrapper';
@@ -99,3 +101,69 @@ describe('useOrganizationEnterpriseConnectionTestRuns — revalidate invalidatio
  invalidateSpy.mockRestore();
  });
 });
+
+describe('useOrganizationEnterpriseConnectionTestRuns — polling arm scope', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('keeps polling armed by a child effect in the same commit the connection arrives', async () => {
+ getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+ let latest: UseOrganizationEnterpriseConnectionTestRunsReturn | undefined;
+
+ // Child effects run before parent effects, so this is the ordering a
+ // reset-in-effect implementation would silently cancel.
+ const Child = ({
+ enterpriseConnectionId,
+ revalidate,
+ }: {
+ enterpriseConnectionId: string | null;
+ revalidate: UseOrganizationEnterpriseConnectionTestRunsReturn['revalidate'];
+ }) => {
+ useEffect(() => {
+ if (enterpriseConnectionId) {
+ void revalidate();
+ }
+ }, [enterpriseConnectionId, revalidate]);
+ return null;
+ };
+
+ const Parent = ({ enterpriseConnectionId }: { enterpriseConnectionId: string | null }) => {
+ latest = __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 });
+ return (
+ <Child
+ enterpriseConnectionId={enterpriseConnectionId}
+ revalidate={latest.revalidate}
+ />
+ );
+ };
+
+ const { rerender } = render(<Parent enterpriseConnectionId={null} />);
+ expect(latest?.isPolling).toBe(false);
+
+ rerender(<Parent enterpriseConnectionId='ent_1' />);
+
+ await waitFor(() => expect(latest?.isPolling).toBe(true));
+ await waitFor(() => expect(getTestRunsSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+ });
+
+ it('disarms polling when the connection changes', async () => {
+ getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+ const { result, rerender } = renderHook(
+ ({ enterpriseConnectionId }: { enterpriseConnectionId: string }) =>
+ __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 }),
+ { wrapper, initialProps: { enterpriseConnectionId: 'ent_1' } },
+ );
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+ expect(result.current.isPolling).toBe(true);
+
+ rerender({ enterpriseConnectionId: 'ent_2' });
+ expect(result.current.isPolling).toBe(false);
+ });
+});

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

@@ -49,6 +49,16 @@ export type {
 } from './useOrganizationEnterpriseConnections';
 export { __internal_useOrganizationDomains } from './useOrganizationDomains';
 export type { UseOrganizationDomainsParams, UseOrganizationDomainsReturn } from './useOrganizationDomains';
+export { __internal_useOrganizationDirectorySync } from './useOrganizationDirectorySync';
+export type {
+ UseOrganizationDirectorySyncParams,
+ UseOrganizationDirectorySyncReturn,
+} from './useOrganizationDirectorySync';
+export { __internal_useOrganizationDirectorySyncUsers } from './useOrganizationDirectorySyncUsers';
+export type {
+ UseOrganizationDirectorySyncUsersParams,
+ UseOrganizationDirectorySyncUsersReturn,
+} from './useOrganizationDirectorySyncUsers';
 export { __internal_useOrganizationEnterpriseConnectionTestRuns } from './useOrganizationEnterpriseConnectionTestRuns';
 export type {
  UseOrganizationEnterpriseConnectionTestRunsParams,

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

@@ -0,0 +1,56 @@
+import { useMemo } from 'react';
+
+import type { GetDirectorySyncUsersParams } from '../../types/directorySync';
+import { INTERNAL_STABLE_KEYS } from '../stable-keys';
+import { createCacheKeys } from './createCacheKeys';
+
+/**
+ * @internal
+ */
+export function useOrganizationDirectorySyncCacheKeys(params: {
+ organizationId: string | null;
+ enterpriseConnectionId: string | null;
+}) {
+ const { organizationId, enterpriseConnectionId } = params;
+ return useMemo(() => {
+ return createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_KEY,
+ authenticated: Boolean(organizationId),
+ tracked: {
+ organizationId: organizationId ?? null,
+ enterpriseConnectionId: enterpriseConnectionId ?? null,
+ },
+ untracked: {
+ args: {},
+ },
+ });
+ }, [organizationId, enterpriseConnectionId]);
+}
+
+/**
+ * @internal
+ */
+export function useOrganizationDirectorySyncUsersCacheKeys(params: {
+ organizationId: string | null;
+ enterpriseConnectionId: string | null;
+ directoryId: string | null;
+ args: GetDirectorySyncUsersParams;
+}) {
+ const { organizationId, enterpriseConnectionId, directoryId, args } = params;
+ return useMemo(() => {
+ return createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_USERS_KEY,
+ authenticated: Boolean(organizationId),
+ tracked: {
+ organizationId: organizationId ?? null,
+ enterpriseConnectionId: enterpriseConnectionId ?? null,
+ directoryId: directoryId ?? null,
+ },
+ untracked: {
+ args,
+ },
+ });
+ // The args object is intentionally serialized via the consumer to keep stability.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [organizationId, enterpriseConnectionId, directoryId, JSON.stringify(args)]);
+}

packages/shared/src/react/hooks/__tests__/useOrganizationDirectorySync.spec.tsx

@@ -0,0 +1,92 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ClerkAPIResponseError } from '@/error';
+
+import { INTERNAL_STABLE_KEYS } from '../../stable-keys';
+import { createCacheKeys } from '../createCacheKeys';
+import { __internal_useOrganizationDirectorySync } from '../useOrganizationDirectorySync';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const directory = { id: 'dir_1', enterpriseConnectionId: 'ent_1' };
+const getDirectorySyncSpy = vi.fn((_enterpriseConnectionId: string) => Promise.resolve(directory));
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ queryClient: defaultQueryClient,
+ __internal_lastEmittedResources: {
+ user: null,
+ session: null,
+ organization: { id: 'org_1', getDirectorySync: getDirectorySyncSpy },
+ client: null,
+ },
+});
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const keysFor = (enterpriseConnectionId: string) =>
+ createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_KEY,
+ authenticated: true,
+ tracked: { organizationId: 'org_1', enterpriseConnectionId },
+ untracked: { args: {} },
+ });
+
+const renderDirectorySync = (enterpriseConnectionId: string | null = 'ent_1') =>
+ renderHook(() => __internal_useOrganizationDirectorySync({ enterpriseConnectionId }), { wrapper });
+
+describe('useOrganizationDirectorySync', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('resolves the directory for the connection', async () => {
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ expect(getDirectorySyncSpy).toHaveBeenCalledWith('ent_1');
+ expect(result.current.data).toBe(directory);
+ expect(result.current.error).toBeNull();
+ });
+
+ it('treats a 404 as "no directory yet" and resolves null instead of an error', async () => {
+ getDirectorySyncSpy.mockRejectedValueOnce(new ClerkAPIResponseError('Not found', { status: 404, data: [] }));
+
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ expect(result.current.data).toBeNull();
+ expect(result.current.error).toBeNull();
+ });
+
+ it('stays dormant without an enterprise connection id', () => {
+ const { result } = renderDirectorySync(null);
+
+ expect(getDirectorySyncSpy).not.toHaveBeenCalled();
+ expect(result.current.data).toBeUndefined();
+ });
+
+ it('revalidate refetches only this org+connection, leaving other connections cached', async () => {
+ const { queryKey: otherKey } = keysFor('ent_other');
+ defaultQueryClient.client.setQueryData(otherKey, { id: 'dir_other', enterpriseConnectionId: 'ent_other' });
+
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(getDirectorySyncSpy).toHaveBeenCalledTimes(1);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ expect(getDirectorySyncSpy).toHaveBeenCalledTimes(2);
+ expect(defaultQueryClient.client.getQueryState(otherKey)?.isInvalidated).toBe(false);
+ });
+});

packages/shared/src/react/hooks/__tests__/useOrganizationDirectorySyncUsers.spec.tsx

@@ -0,0 +1,121 @@
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { DirectorySyncResource } from '@/types/directorySync';
+
+import type { UseOrganizationDirectorySyncUsersReturn } from '../useOrganizationDirectorySyncUsers';
+import { __internal_useOrganizationDirectorySyncUsers } from '../useOrganizationDirectorySyncUsers';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const POLL_INTERVAL_MS = 20;
+
+const getUsersSpy = vi.fn(() => Promise.resolve({ data: [{ id: 'du_1' }], total_count: 1 }));
+
+const createDirectory = (id: string) =>
+ ({ id, enterpriseConnectionId: 'ent_1', getUsers: getUsersSpy }) as unknown as DirectorySyncResource;
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ queryClient: defaultQueryClient,
+ __internal_lastEmittedResources: {
+ user: null,
+ session: null,
+ organization: { id: 'org_1' },
+ client: null,
+ },
+});
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const renderUsers = (initialDirectory: DirectorySyncResource | null) =>
+ renderHook(
+ ({ directory }: { directory: DirectorySyncResource | null }) =>
+ __internal_useOrganizationDirectorySyncUsers({ directory, pollIntervalMs: POLL_INTERVAL_MS }),
+ { wrapper, initialProps: { directory: initialDirectory } },
+ );
+
+describe('useOrganizationDirectorySyncUsers', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('stays dormant without a directory', () => {
+ const { result } = renderUsers(null);
+
+ expect(getUsersSpy).not.toHaveBeenCalled();
+ expect(result.current.data).toBeUndefined();
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('polls while armed and stops on stopPolling', async () => {
+ const { result } = renderUsers(createDirectory('dir_1'));
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.isPolling).toBe(false);
+
+ act(() => result.current.startPolling());
+ expect(result.current.isPolling).toBe(true);
+ await waitFor(() => expect(getUsersSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+
+ act(() => result.current.stopPolling());
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('disarms polling when the directory identity changes', async () => {
+ const { result, rerender } = renderUsers(createDirectory('dir_1'));
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ act(() => result.current.startPolling());
+ expect(result.current.isPolling).toBe(true);
+
+ rerender({ directory: createDirectory('dir_2') });
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('keeps polling armed by a child effect in the same commit the directory arrives', async () => {
+ let latest: UseOrganizationDirectorySyncUsersReturn | undefined;
+
+ // Child effects run before parent effects, so this is the ordering a
+ // reset-in-effect implementation would silently cancel.
+ const Child = ({
+ directory,
+ startPolling,
+ }: {
+ directory: DirectorySyncResource | null;
+ startPolling: () => void;
+ }) => {
+ useEffect(() => {
+ if (directory) {
+ startPolling();
+ }
+ }, [directory, startPolling]);
+ return null;
+ };
+
+ const Parent = ({ directory }: { directory: DirectorySyncResource | null }) => {
+ latest = __internal_useOrganizationDirectorySyncUsers({ directory, pollIntervalMs: POLL_INTERVAL_MS });
+ return (
+ <Child
+ directory={directory}
+ startPolling={latest.startPolling}
+ />
+ );
+ };
+
+ const { rerender } = render(<Parent directory={null} />);
+ expect(latest?.isPolling).toBe(false);
+
+ rerender(<Parent directory={createDirectory('dir_1')} />);
+
+ await waitFor(() => expect(latest?.isPolling).toBe(true));
+ await waitFor(() => expect(getUsersSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+ });
+});

packages/shared/src/react/hooks/__tests__/useOrganizationEnterpriseConnectionTestRuns.spec.tsx

@@ -1,10 +1,12 @@
-import { act, renderHook, waitFor } from '@testing-library/react';
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { GetEnterpriseConnectionTestRunsParams } from '@/types/enterpriseConnectionTestRun';
 
 import { INTERNAL_STABLE_KEYS } from '../../stable-keys';
 import { createCacheKeys } from '../createCacheKeys';
+import type { UseOrganizationEnterpriseConnectionTestRunsReturn } from '../useOrganizationEnterpriseConnectionTestRuns';
 import { __internal_useOrganizationEnterpriseConnectionTestRuns } from '../useOrganizationEnterpriseConnectionTestRuns';
 import { createMockClerk, createMockQueryClient } from './mocks/clerk';
 import { wrapper } from './wrapper';
@@ -99,3 +101,69 @@ describe('useOrganizationEnterpriseConnectionTestRuns — revalidate invalidatio
  invalidateSpy.mockRestore();
  });
 });
+
+describe('useOrganizationEnterpriseConnectionTestRuns — polling arm scope', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('keeps polling armed by a child effect in the same commit the connection arrives', async () => {
+ getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+ let latest: UseOrganizationEnterpriseConnectionTestRunsReturn | undefined;
+
+ // Child effects run before parent effects, so this is the ordering a
+ // reset-in-effect implementation would silently cancel.
+ const Child = ({
+ enterpriseConnectionId,
+ revalidate,
+ }: {
+ enterpriseConnectionId: string | null;
+ revalidate: UseOrganizationEnterpriseConnectionTestRunsReturn['revalidate'];
+ }) => {
+ useEffect(() => {
+ if (enterpriseConnectionId) {
+ void revalidate();
+ }
+ }, [enterpriseConnectionId, revalidate]);
+ return null;
+ };
+
+ const Parent = ({ enterpriseConnectionId }: { enterpriseConnectionId: string | null }) => {
+ latest = __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 });
+ return (
+ <Child
+ enterpriseConnectionId={enterpriseConnectionId}
+ revalidate={latest.revalidate}
+ />
+ );
+ };
+
+ const { rerender } = render(<Parent enterpriseConnectionId={null} />);
+ expect(latest?.isPolling).toBe(false);
+
+ rerender(<Parent enterpriseConnectionId='ent_1' />);
+
+ await waitFor(() => expect(latest?.isPolling).toBe(true));
+ await waitFor(() => expect(getTestRunsSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+ });
+
+ it('disarms polling when the connection changes', async () => {
+ getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+ const { result, rerender } = renderHook(
+ ({ enterpriseConnectionId }: { enterpriseConnectionId: string }) =>
+ __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 }),
+ { wrapper, initialProps: { enterpriseConnectionId: 'ent_1' } },
+ );
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+ expect(result.current.isPolling).toBe(true);
+
+ rerender({ enterpriseConnectionId: 'ent_2' });
+ expect(result.current.isPolling).toBe(false);
+ });
+});

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

@@ -49,6 +49,16 @@ export type {
 } from './useOrganizationEnterpriseConnections';
 export { __internal_useOrganizationDomains } from './useOrganizationDomains';
 export type { UseOrganizationDomainsParams, UseOrganizationDomainsReturn } from './useOrganizationDomains';
+export { __internal_useOrganizationDirectorySync } from './useOrganizationDirectorySync';
+export type {
+ UseOrganizationDirectorySyncParams,
+ UseOrganizationDirectorySyncReturn,
+} from './useOrganizationDirectorySync';
+export { __internal_useOrganizationDirectorySyncUsers } from './useOrganizationDirectorySyncUsers';
+export type {
+ UseOrganizationDirectorySyncUsersParams,
+ UseOrganizationDirectorySyncUsersReturn,
+} from './useOrganizationDirectorySyncUsers';
 export { __internal_useOrganizationEnterpriseConnectionTestRuns } from './useOrganizationEnterpriseConnectionTestRuns';
 export type {
  UseOrganizationEnterpriseConnectionTestRunsParams,

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

@@ -0,0 +1,56 @@
+import { useMemo } from 'react';
+
+import type { GetDirectorySyncUsersParams } from '../../types/directorySync';
+import { INTERNAL_STABLE_KEYS } from '../stable-keys';
+import { createCacheKeys } from './createCacheKeys';
+
+/**
+ * @internal
+ */
+export function useOrganizationDirectorySyncCacheKeys(params: {
+ organizationId: string | null;
+ enterpriseConnectionId: string | null;
+}) {
+ const { organizationId, enterpriseConnectionId } = params;
+ return useMemo(() => {
+ return createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_KEY,
+ authenticated: Boolean(organizationId),
+ tracked: {
+ organizationId: organizationId ?? null,
+ enterpriseConnectionId: enterpriseConnectionId ?? null,
+ },
+ untracked: {
+ args: {},
+ },
+ });
+ }, [organizationId, enterpriseConnectionId]);
+}
+
+/**
+ * @internal
+ */
+export function useOrganizationDirectorySyncUsersCacheKeys(params: {
+ organizationId: string | null;
+ enterpriseConnectionId: string | null;
+ directoryId: string | null;
+ args: GetDirectorySyncUsersParams;
+}) {
+ const { organizationId, enterpriseConnectionId, directoryId, args } = params;
+ return useMemo(() => {
+ return createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_USERS_KEY,
+ authenticated: Boolean(organizationId),
+ tracked: {
+ organizationId: organizationId ?? null,
+ enterpriseConnectionId: enterpriseConnectionId ?? null,
+ directoryId: directoryId ?? null,
+ },
+ untracked: {
+ args,
+ },
+ });
+ // The args object is intentionally serialized via the consumer to keep stability.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [organizationId, enterpriseConnectionId, directoryId, JSON.stringify(args)]);
+}

packages/shared/src/react/hooks/__tests__/useOrganizationDirectorySync.spec.tsx

@@ -0,0 +1,92 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ClerkAPIResponseError } from '@/error';
+
+import { INTERNAL_STABLE_KEYS } from '../../stable-keys';
+import { createCacheKeys } from '../createCacheKeys';
+import { __internal_useOrganizationDirectorySync } from '../useOrganizationDirectorySync';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const directory = { id: 'dir_1', enterpriseConnectionId: 'ent_1' };
+const getDirectorySyncSpy = vi.fn((_enterpriseConnectionId: string) => Promise.resolve(directory));
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ queryClient: defaultQueryClient,
+ __internal_lastEmittedResources: {
+ user: null,
+ session: null,
+ organization: { id: 'org_1', getDirectorySync: getDirectorySyncSpy },
+ client: null,
+ },
+});
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const keysFor = (enterpriseConnectionId: string) =>
+ createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_KEY,
+ authenticated: true,
+ tracked: { organizationId: 'org_1', enterpriseConnectionId },
+ untracked: { args: {} },
+ });
+
+const renderDirectorySync = (enterpriseConnectionId: string | null = 'ent_1') =>
+ renderHook(() => __internal_useOrganizationDirectorySync({ enterpriseConnectionId }), { wrapper });
+
+describe('useOrganizationDirectorySync', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('resolves the directory for the connection', async () => {
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ expect(getDirectorySyncSpy).toHaveBeenCalledWith('ent_1');
+ expect(result.current.data).toBe(directory);
+ expect(result.current.error).toBeNull();
+ });
+
+ it('treats a 404 as "no directory yet" and resolves null instead of an error', async () => {
+ getDirectorySyncSpy.mockRejectedValueOnce(new ClerkAPIResponseError('Not found', { status: 404, data: [] }));
+
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ expect(result.current.data).toBeNull();
+ expect(result.current.error).toBeNull();
+ });
+
+ it('stays dormant without an enterprise connection id', () => {
+ const { result } = renderDirectorySync(null);
+
+ expect(getDirectorySyncSpy).not.toHaveBeenCalled();
+ expect(result.current.data).toBeUndefined();
+ });
+
+ it('revalidate refetches only this org+connection, leaving other connections cached', async () => {
+ const { queryKey: otherKey } = keysFor('ent_other');
+ defaultQueryClient.client.setQueryData(otherKey, { id: 'dir_other', enterpriseConnectionId: 'ent_other' });
+
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(getDirectorySyncSpy).toHaveBeenCalledTimes(1);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ expect(getDirectorySyncSpy).toHaveBeenCalledTimes(2);
+ expect(defaultQueryClient.client.getQueryState(otherKey)?.isInvalidated).toBe(false);
+ });
+});

packages/shared/src/react/hooks/__tests__/useOrganizationDirectorySyncUsers.spec.tsx

@@ -0,0 +1,121 @@
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { DirectorySyncResource } from '@/types/directorySync';
+
+import type { UseOrganizationDirectorySyncUsersReturn } from '../useOrganizationDirectorySyncUsers';
+import { __internal_useOrganizationDirectorySyncUsers } from '../useOrganizationDirectorySyncUsers';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const POLL_INTERVAL_MS = 20;
+
+const getUsersSpy = vi.fn(() => Promise.resolve({ data: [{ id: 'du_1' }], total_count: 1 }));
+
+const createDirectory = (id: string) =>
+ ({ id, enterpriseConnectionId: 'ent_1', getUsers: getUsersSpy }) as unknown as DirectorySyncResource;
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ queryClient: defaultQueryClient,
+ __internal_lastEmittedResources: {
+ user: null,
+ session: null,
+ organization: { id: 'org_1' },
+ client: null,
+ },
+});
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const renderUsers = (initialDirectory: DirectorySyncResource | null) =>
+ renderHook(
+ ({ directory }: { directory: DirectorySyncResource | null }) =>
+ __internal_useOrganizationDirectorySyncUsers({ directory, pollIntervalMs: POLL_INTERVAL_MS }),
+ { wrapper, initialProps: { directory: initialDirectory } },
+ );
+
+describe('useOrganizationDirectorySyncUsers', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('stays dormant without a directory', () => {
+ const { result } = renderUsers(null);
+
+ expect(getUsersSpy).not.toHaveBeenCalled();
+ expect(result.current.data).toBeUndefined();
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('polls while armed and stops on stopPolling', async () => {
+ const { result } = renderUsers(createDirectory('dir_1'));
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.isPolling).toBe(false);
+
+ act(() => result.current.startPolling());
+ expect(result.current.isPolling).toBe(true);
+ await waitFor(() => expect(getUsersSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+
+ act(() => result.current.stopPolling());
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('disarms polling when the directory identity changes', async () => {
+ const { result, rerender } = renderUsers(createDirectory('dir_1'));
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ act(() => result.current.startPolling());
+ expect(result.current.isPolling).toBe(true);
+
+ rerender({ directory: createDirectory('dir_2') });
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('keeps polling armed by a child effect in the same commit the directory arrives', async () => {
+ let latest: UseOrganizationDirectorySyncUsersReturn | undefined;
+
+ // Child effects run before parent effects, so this is the ordering a
+ // reset-in-effect implementation would silently cancel.
+ const Child = ({
+ directory,
+ startPolling,
+ }: {
+ directory: DirectorySyncResource | null;
+ startPolling: () => void;
+ }) => {
+ useEffect(() => {
+ if (directory) {
+ startPolling();
+ }
+ }, [directory, startPolling]);
+ return null;
+ };
+
+ const Parent = ({ directory }: { directory: DirectorySyncResource | null }) => {
+ latest = __internal_useOrganizationDirectorySyncUsers({ directory, pollIntervalMs: POLL_INTERVAL_MS });
+ return (
+ <Child
+ directory={directory}
+ startPolling={latest.startPolling}
+ />
+ );
+ };
+
+ const { rerender } = render(<Parent directory={null} />);
+ expect(latest?.isPolling).toBe(false);
+
+ rerender(<Parent directory={createDirectory('dir_1')} />);
+
+ await waitFor(() => expect(latest?.isPolling).toBe(true));
+ await waitFor(() => expect(getUsersSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+ });
+});

packages/shared/src/react/hooks/__tests__/useOrganizationEnterpriseConnectionTestRuns.spec.tsx

@@ -1,10 +1,12 @@
-import { act, renderHook, waitFor } from '@testing-library/react';
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { GetEnterpriseConnectionTestRunsParams } from '@/types/enterpriseConnectionTestRun';
 
 import { INTERNAL_STABLE_KEYS } from '../../stable-keys';
 import { createCacheKeys } from '../createCacheKeys';
+import type { UseOrganizationEnterpriseConnectionTestRunsReturn } from '../useOrganizationEnterpriseConnectionTestRuns';
 import { __internal_useOrganizationEnterpriseConnectionTestRuns } from '../useOrganizationEnterpriseConnectionTestRuns';
 import { createMockClerk, createMockQueryClient } from './mocks/clerk';
 import { wrapper } from './wrapper';
@@ -99,3 +101,69 @@ describe('useOrganizationEnterpriseConnectionTestRuns — revalidate invalidatio
  invalidateSpy.mockRestore();
  });
 });
+
+describe('useOrganizationEnterpriseConnectionTestRuns — polling arm scope', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('keeps polling armed by a child effect in the same commit the connection arrives', async () => {
+ getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+ let latest: UseOrganizationEnterpriseConnectionTestRunsReturn | undefined;
+
+ // Child effects run before parent effects, so this is the ordering a
+ // reset-in-effect implementation would silently cancel.
+ const Child = ({
+ enterpriseConnectionId,
+ revalidate,
+ }: {
+ enterpriseConnectionId: string | null;
+ revalidate: UseOrganizationEnterpriseConnectionTestRunsReturn['revalidate'];
+ }) => {
+ useEffect(() => {
+ if (enterpriseConnectionId) {
+ void revalidate();
+ }
+ }, [enterpriseConnectionId, revalidate]);
+ return null;
+ };
+
+ const Parent = ({ enterpriseConnectionId }: { enterpriseConnectionId: string | null }) => {
+ latest = __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 });
+ return (
+ <Child
+ enterpriseConnectionId={enterpriseConnectionId}
+ revalidate={latest.revalidate}
+ />
+ );
+ };
+
+ const { rerender } = render(<Parent enterpriseConnectionId={null} />);
+ expect(latest?.isPolling).toBe(false);
+
+ rerender(<Parent enterpriseConnectionId='ent_1' />);
+
+ await waitFor(() => expect(latest?.isPolling).toBe(true));
+ await waitFor(() => expect(getTestRunsSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+ });
+
+ it('disarms polling when the connection changes', async () => {
+ getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+ const { result, rerender } = renderHook(
+ ({ enterpriseConnectionId }: { enterpriseConnectionId: string }) =>
+ __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 }),
+ { wrapper, initialProps: { enterpriseConnectionId: 'ent_1' } },
+ );
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+ expect(result.current.isPolling).toBe(true);
+
+ rerender({ enterpriseConnectionId: 'ent_2' });
+ expect(result.current.isPolling).toBe(false);
+ });
+});

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

@@ -49,6 +49,16 @@ export type {
 } from './useOrganizationEnterpriseConnections';
 export { __internal_useOrganizationDomains } from './useOrganizationDomains';
 export type { UseOrganizationDomainsParams, UseOrganizationDomainsReturn } from './useOrganizationDomains';
+export { __internal_useOrganizationDirectorySync } from './useOrganizationDirectorySync';
+export type {
+ UseOrganizationDirectorySyncParams,
+ UseOrganizationDirectorySyncReturn,
+} from './useOrganizationDirectorySync';
+export { __internal_useOrganizationDirectorySyncUsers } from './useOrganizationDirectorySyncUsers';
+export type {
+ UseOrganizationDirectorySyncUsersParams,
+ UseOrganizationDirectorySyncUsersReturn,
+} from './useOrganizationDirectorySyncUsers';
 export { __internal_useOrganizationEnterpriseConnectionTestRuns } from './useOrganizationEnterpriseConnectionTestRuns';
 export type {
  UseOrganizationEnterpriseConnectionTestRunsParams,

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

@@ -0,0 +1,56 @@
+import { useMemo } from 'react';
+
+import type { GetDirectorySyncUsersParams } from '../../types/directorySync';
+import { INTERNAL_STABLE_KEYS } from '../stable-keys';
+import { createCacheKeys } from './createCacheKeys';
+
+/**
+ * @internal
+ */
+export function useOrganizationDirectorySyncCacheKeys(params: {
+ organizationId: string | null;
+ enterpriseConnectionId: string | null;
+}) {
+ const { organizationId, enterpriseConnectionId } = params;
+ return useMemo(() => {
+ return createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_KEY,
+ authenticated: Boolean(organizationId),
+ tracked: {
+ organizationId: organizationId ?? null,
+ enterpriseConnectionId: enterpriseConnectionId ?? null,
+ },
+ untracked: {
+ args: {},
+ },
+ });
+ }, [organizationId, enterpriseConnectionId]);
+}
+
+/**
+ * @internal
+ */
+export function useOrganizationDirectorySyncUsersCacheKeys(params: {
+ organizationId: string | null;
+ enterpriseConnectionId: string | null;
+ directoryId: string | null;
+ args: GetDirectorySyncUsersParams;
+}) {
+ const { organizationId, enterpriseConnectionId, directoryId, args } = params;
+ return useMemo(() => {
+ return createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_USERS_KEY,
+ authenticated: Boolean(organizationId),
+ tracked: {
+ organizationId: organizationId ?? null,
+ enterpriseConnectionId: enterpriseConnectionId ?? null,
+ directoryId: directoryId ?? null,
+ },
+ untracked: {
+ args,
+ },
+ });
+ // The args object is intentionally serialized via the consumer to keep stability.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [organizationId, enterpriseConnectionId, directoryId, JSON.stringify(args)]);
+}

packages/shared/src/react/hooks/__tests__/useOrganizationDirectorySync.spec.tsx

@@ -0,0 +1,92 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ClerkAPIResponseError } from '@/error';
+
+import { INTERNAL_STABLE_KEYS } from '../../stable-keys';
+import { createCacheKeys } from '../createCacheKeys';
+import { __internal_useOrganizationDirectorySync } from '../useOrganizationDirectorySync';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const directory = { id: 'dir_1', enterpriseConnectionId: 'ent_1' };
+const getDirectorySyncSpy = vi.fn((_enterpriseConnectionId: string) => Promise.resolve(directory));
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ queryClient: defaultQueryClient,
+ __internal_lastEmittedResources: {
+ user: null,
+ session: null,
+ organization: { id: 'org_1', getDirectorySync: getDirectorySyncSpy },
+ client: null,
+ },
+});
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const keysFor = (enterpriseConnectionId: string) =>
+ createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_KEY,
+ authenticated: true,
+ tracked: { organizationId: 'org_1', enterpriseConnectionId },
+ untracked: { args: {} },
+ });
+
+const renderDirectorySync = (enterpriseConnectionId: string | null = 'ent_1') =>
+ renderHook(() => __internal_useOrganizationDirectorySync({ enterpriseConnectionId }), { wrapper });
+
+describe('useOrganizationDirectorySync', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('resolves the directory for the connection', async () => {
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ expect(getDirectorySyncSpy).toHaveBeenCalledWith('ent_1');
+ expect(result.current.data).toBe(directory);
+ expect(result.current.error).toBeNull();
+ });
+
+ it('treats a 404 as "no directory yet" and resolves null instead of an error', async () => {
+ getDirectorySyncSpy.mockRejectedValueOnce(new ClerkAPIResponseError('Not found', { status: 404, data: [] }));
+
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ expect(result.current.data).toBeNull();
+ expect(result.current.error).toBeNull();
+ });
+
+ it('stays dormant without an enterprise connection id', () => {
+ const { result } = renderDirectorySync(null);
+
+ expect(getDirectorySyncSpy).not.toHaveBeenCalled();
+ expect(result.current.data).toBeUndefined();
+ });
+
+ it('revalidate refetches only this org+connection, leaving other connections cached', async () => {
+ const { queryKey: otherKey } = keysFor('ent_other');
+ defaultQueryClient.client.setQueryData(otherKey, { id: 'dir_other', enterpriseConnectionId: 'ent_other' });
+
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(getDirectorySyncSpy).toHaveBeenCalledTimes(1);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ expect(getDirectorySyncSpy).toHaveBeenCalledTimes(2);
+ expect(defaultQueryClient.client.getQueryState(otherKey)?.isInvalidated).toBe(false);
+ });
+});

packages/shared/src/react/hooks/__tests__/useOrganizationDirectorySyncUsers.spec.tsx

@@ -0,0 +1,121 @@
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { DirectorySyncResource } from '@/types/directorySync';
+
+import type { UseOrganizationDirectorySyncUsersReturn } from '../useOrganizationDirectorySyncUsers';
+import { __internal_useOrganizationDirectorySyncUsers } from '../useOrganizationDirectorySyncUsers';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const POLL_INTERVAL_MS = 20;
+
+const getUsersSpy = vi.fn(() => Promise.resolve({ data: [{ id: 'du_1' }], total_count: 1 }));
+
+const createDirectory = (id: string) =>
+ ({ id, enterpriseConnectionId: 'ent_1', getUsers: getUsersSpy }) as unknown as DirectorySyncResource;
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ queryClient: defaultQueryClient,
+ __internal_lastEmittedResources: {
+ user: null,
+ session: null,
+ organization: { id: 'org_1' },
+ client: null,
+ },
+});
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const renderUsers = (initialDirectory: DirectorySyncResource | null) =>
+ renderHook(
+ ({ directory }: { directory: DirectorySyncResource | null }) =>
+ __internal_useOrganizationDirectorySyncUsers({ directory, pollIntervalMs: POLL_INTERVAL_MS }),
+ { wrapper, initialProps: { directory: initialDirectory } },
+ );
+
+describe('useOrganizationDirectorySyncUsers', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('stays dormant without a directory', () => {
+ const { result } = renderUsers(null);
+
+ expect(getUsersSpy).not.toHaveBeenCalled();
+ expect(result.current.data).toBeUndefined();
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('polls while armed and stops on stopPolling', async () => {
+ const { result } = renderUsers(createDirectory('dir_1'));
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.isPolling).toBe(false);
+
+ act(() => result.current.startPolling());
+ expect(result.current.isPolling).toBe(true);
+ await waitFor(() => expect(getUsersSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+
+ act(() => result.current.stopPolling());
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('disarms polling when the directory identity changes', async () => {
+ const { result, rerender } = renderUsers(createDirectory('dir_1'));
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ act(() => result.current.startPolling());
+ expect(result.current.isPolling).toBe(true);
+
+ rerender({ directory: createDirectory('dir_2') });
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('keeps polling armed by a child effect in the same commit the directory arrives', async () => {
+ let latest: UseOrganizationDirectorySyncUsersReturn | undefined;
+
+ // Child effects run before parent effects, so this is the ordering a
+ // reset-in-effect implementation would silently cancel.
+ const Child = ({
+ directory,
+ startPolling,
+ }: {
+ directory: DirectorySyncResource | null;
+ startPolling: () => void;
+ }) => {
+ useEffect(() => {
+ if (directory) {
+ startPolling();
+ }
+ }, [directory, startPolling]);
+ return null;
+ };
+
+ const Parent = ({ directory }: { directory: DirectorySyncResource | null }) => {
+ latest = __internal_useOrganizationDirectorySyncUsers({ directory, pollIntervalMs: POLL_INTERVAL_MS });
+ return (
+ <Child
+ directory={directory}
+ startPolling={latest.startPolling}
+ />
+ );
+ };
+
+ const { rerender } = render(<Parent directory={null} />);
+ expect(latest?.isPolling).toBe(false);
+
+ rerender(<Parent directory={createDirectory('dir_1')} />);
+
+ await waitFor(() => expect(latest?.isPolling).toBe(true));
+ await waitFor(() => expect(getUsersSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+ });
+});

packages/shared/src/react/hooks/__tests__/useOrganizationEnterpriseConnectionTestRuns.spec.tsx

@@ -1,10 +1,12 @@
-import { act, renderHook, waitFor } from '@testing-library/react';
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { GetEnterpriseConnectionTestRunsParams } from '@/types/enterpriseConnectionTestRun';
 
 import { INTERNAL_STABLE_KEYS } from '../../stable-keys';
 import { createCacheKeys } from '../createCacheKeys';
+import type { UseOrganizationEnterpriseConnectionTestRunsReturn } from '../useOrganizationEnterpriseConnectionTestRuns';
 import { __internal_useOrganizationEnterpriseConnectionTestRuns } from '../useOrganizationEnterpriseConnectionTestRuns';
 import { createMockClerk, createMockQueryClient } from './mocks/clerk';
 import { wrapper } from './wrapper';
@@ -99,3 +101,69 @@ describe('useOrganizationEnterpriseConnectionTestRuns — revalidate invalidatio
  invalidateSpy.mockRestore();
  });
 });
+
+describe('useOrganizationEnterpriseConnectionTestRuns — polling arm scope', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('keeps polling armed by a child effect in the same commit the connection arrives', async () => {
+ getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+ let latest: UseOrganizationEnterpriseConnectionTestRunsReturn | undefined;
+
+ // Child effects run before parent effects, so this is the ordering a
+ // reset-in-effect implementation would silently cancel.
+ const Child = ({
+ enterpriseConnectionId,
+ revalidate,
+ }: {
+ enterpriseConnectionId: string | null;
+ revalidate: UseOrganizationEnterpriseConnectionTestRunsReturn['revalidate'];
+ }) => {
+ useEffect(() => {
+ if (enterpriseConnectionId) {
+ void revalidate();
+ }
+ }, [enterpriseConnectionId, revalidate]);
+ return null;
+ };
+
+ const Parent = ({ enterpriseConnectionId }: { enterpriseConnectionId: string | null }) => {
+ latest = __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 });
+ return (
+ <Child
+ enterpriseConnectionId={enterpriseConnectionId}
+ revalidate={latest.revalidate}
+ />
+ );
+ };
+
+ const { rerender } = render(<Parent enterpriseConnectionId={null} />);
+ expect(latest?.isPolling).toBe(false);
+
+ rerender(<Parent enterpriseConnectionId='ent_1' />);
+
+ await waitFor(() => expect(latest?.isPolling).toBe(true));
+ await waitFor(() => expect(getTestRunsSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+ });
+
+ it('disarms polling when the connection changes', async () => {
+ getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+ const { result, rerender } = renderHook(
+ ({ enterpriseConnectionId }: { enterpriseConnectionId: string }) =>
+ __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 }),
+ { wrapper, initialProps: { enterpriseConnectionId: 'ent_1' } },
+ );
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+ expect(result.current.isPolling).toBe(true);
+
+ rerender({ enterpriseConnectionId: 'ent_2' });
+ expect(result.current.isPolling).toBe(false);
+ });
+});

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

@@ -49,6 +49,16 @@ export type {
 } from './useOrganizationEnterpriseConnections';
 export { __internal_useOrganizationDomains } from './useOrganizationDomains';
 export type { UseOrganizationDomainsParams, UseOrganizationDomainsReturn } from './useOrganizationDomains';
+export { __internal_useOrganizationDirectorySync } from './useOrganizationDirectorySync';
+export type {
+ UseOrganizationDirectorySyncParams,
+ UseOrganizationDirectorySyncReturn,
+} from './useOrganizationDirectorySync';
+export { __internal_useOrganizationDirectorySyncUsers } from './useOrganizationDirectorySyncUsers';
+export type {
+ UseOrganizationDirectorySyncUsersParams,
+ UseOrganizationDirectorySyncUsersReturn,
+} from './useOrganizationDirectorySyncUsers';
 export { __internal_useOrganizationEnterpriseConnectionTestRuns } from './useOrganizationEnterpriseConnectionTestRuns';
 export type {
  UseOrganizationEnterpriseConnectionTestRunsParams,

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

@@ -0,0 +1,56 @@
+import { useMemo } from 'react';
+
+import type { GetDirectorySyncUsersParams } from '../../types/directorySync';
+import { INTERNAL_STABLE_KEYS } from '../stable-keys';
+import { createCacheKeys } from './createCacheKeys';
+
+/**
+ * @internal
+ */
+export function useOrganizationDirectorySyncCacheKeys(params: {
+ organizationId: string | null;
+ enterpriseConnectionId: string | null;
+}) {
+ const { organizationId, enterpriseConnectionId } = params;
+ return useMemo(() => {
+ return createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_KEY,
+ authenticated: Boolean(organizationId),
+ tracked: {
+ organizationId: organizationId ?? null,
+ enterpriseConnectionId: enterpriseConnectionId ?? null,
+ },
+ untracked: {
+ args: {},
+ },
+ });
+ }, [organizationId, enterpriseConnectionId]);
+}
+
+/**
+ * @internal
+ */
+export function useOrganizationDirectorySyncUsersCacheKeys(params: {
+ organizationId: string | null;
+ enterpriseConnectionId: string | null;
+ directoryId: string | null;
+ args: GetDirectorySyncUsersParams;
+}) {
+ const { organizationId, enterpriseConnectionId, directoryId, args } = params;
+ return useMemo(() => {
+ return createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_USERS_KEY,
+ authenticated: Boolean(organizationId),
+ tracked: {
+ organizationId: organizationId ?? null,
+ enterpriseConnectionId: enterpriseConnectionId ?? null,
+ directoryId: directoryId ?? null,
+ },
+ untracked: {
+ args,
+ },
+ });
+ // The args object is intentionally serialized via the consumer to keep stability.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [organizationId, enterpriseConnectionId, directoryId, JSON.stringify(args)]);
+}

packages/shared/src/react/hooks/__tests__/useOrganizationDirectorySync.spec.tsx

@@ -0,0 +1,92 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ClerkAPIResponseError } from '@/error';
+
+import { INTERNAL_STABLE_KEYS } from '../../stable-keys';
+import { createCacheKeys } from '../createCacheKeys';
+import { __internal_useOrganizationDirectorySync } from '../useOrganizationDirectorySync';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const directory = { id: 'dir_1', enterpriseConnectionId: 'ent_1' };
+const getDirectorySyncSpy = vi.fn((_enterpriseConnectionId: string) => Promise.resolve(directory));
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ queryClient: defaultQueryClient,
+ __internal_lastEmittedResources: {
+ user: null,
+ session: null,
+ organization: { id: 'org_1', getDirectorySync: getDirectorySyncSpy },
+ client: null,
+ },
+});
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const keysFor = (enterpriseConnectionId: string) =>
+ createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_KEY,
+ authenticated: true,
+ tracked: { organizationId: 'org_1', enterpriseConnectionId },
+ untracked: { args: {} },
+ });
+
+const renderDirectorySync = (enterpriseConnectionId: string | null = 'ent_1') =>
+ renderHook(() => __internal_useOrganizationDirectorySync({ enterpriseConnectionId }), { wrapper });
+
+describe('useOrganizationDirectorySync', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('resolves the directory for the connection', async () => {
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ expect(getDirectorySyncSpy).toHaveBeenCalledWith('ent_1');
+ expect(result.current.data).toBe(directory);
+ expect(result.current.error).toBeNull();
+ });
+
+ it('treats a 404 as "no directory yet" and resolves null instead of an error', async () => {
+ getDirectorySyncSpy.mockRejectedValueOnce(new ClerkAPIResponseError('Not found', { status: 404, data: [] }));
+
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ expect(result.current.data).toBeNull();
+ expect(result.current.error).toBeNull();
+ });
+
+ it('stays dormant without an enterprise connection id', () => {
+ const { result } = renderDirectorySync(null);
+
+ expect(getDirectorySyncSpy).not.toHaveBeenCalled();
+ expect(result.current.data).toBeUndefined();
+ });
+
+ it('revalidate refetches only this org+connection, leaving other connections cached', async () => {
+ const { queryKey: otherKey } = keysFor('ent_other');
+ defaultQueryClient.client.setQueryData(otherKey, { id: 'dir_other', enterpriseConnectionId: 'ent_other' });
+
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(getDirectorySyncSpy).toHaveBeenCalledTimes(1);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ expect(getDirectorySyncSpy).toHaveBeenCalledTimes(2);
+ expect(defaultQueryClient.client.getQueryState(otherKey)?.isInvalidated).toBe(false);
+ });
+});

packages/shared/src/react/hooks/__tests__/useOrganizationDirectorySyncUsers.spec.tsx

@@ -0,0 +1,121 @@
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { DirectorySyncResource } from '@/types/directorySync';
+
+import type { UseOrganizationDirectorySyncUsersReturn } from '../useOrganizationDirectorySyncUsers';
+import { __internal_useOrganizationDirectorySyncUsers } from '../useOrganizationDirectorySyncUsers';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const POLL_INTERVAL_MS = 20;
+
+const getUsersSpy = vi.fn(() => Promise.resolve({ data: [{ id: 'du_1' }], total_count: 1 }));
+
+const createDirectory = (id: string) =>
+ ({ id, enterpriseConnectionId: 'ent_1', getUsers: getUsersSpy }) as unknown as DirectorySyncResource;
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ queryClient: defaultQueryClient,
+ __internal_lastEmittedResources: {
+ user: null,
+ session: null,
+ organization: { id: 'org_1' },
+ client: null,
+ },
+});
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const renderUsers = (initialDirectory: DirectorySyncResource | null) =>
+ renderHook(
+ ({ directory }: { directory: DirectorySyncResource | null }) =>
+ __internal_useOrganizationDirectorySyncUsers({ directory, pollIntervalMs: POLL_INTERVAL_MS }),
+ { wrapper, initialProps: { directory: initialDirectory } },
+ );
+
+describe('useOrganizationDirectorySyncUsers', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('stays dormant without a directory', () => {
+ const { result } = renderUsers(null);
+
+ expect(getUsersSpy).not.toHaveBeenCalled();
+ expect(result.current.data).toBeUndefined();
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('polls while armed and stops on stopPolling', async () => {
+ const { result } = renderUsers(createDirectory('dir_1'));
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.isPolling).toBe(false);
+
+ act(() => result.current.startPolling());
+ expect(result.current.isPolling).toBe(true);
+ await waitFor(() => expect(getUsersSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+
+ act(() => result.current.stopPolling());
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('disarms polling when the directory identity changes', async () => {
+ const { result, rerender } = renderUsers(createDirectory('dir_1'));
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ act(() => result.current.startPolling());
+ expect(result.current.isPolling).toBe(true);
+
+ rerender({ directory: createDirectory('dir_2') });
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('keeps polling armed by a child effect in the same commit the directory arrives', async () => {
+ let latest: UseOrganizationDirectorySyncUsersReturn | undefined;
+
+ // Child effects run before parent effects, so this is the ordering a
+ // reset-in-effect implementation would silently cancel.
+ const Child = ({
+ directory,
+ startPolling,
+ }: {
+ directory: DirectorySyncResource | null;
+ startPolling: () => void;
+ }) => {
+ useEffect(() => {
+ if (directory) {
+ startPolling();
+ }
+ }, [directory, startPolling]);
+ return null;
+ };
+
+ const Parent = ({ directory }: { directory: DirectorySyncResource | null }) => {
+ latest = __internal_useOrganizationDirectorySyncUsers({ directory, pollIntervalMs: POLL_INTERVAL_MS });
+ return (
+ <Child
+ directory={directory}
+ startPolling={latest.startPolling}
+ />
+ );
+ };
+
+ const { rerender } = render(<Parent directory={null} />);
+ expect(latest?.isPolling).toBe(false);
+
+ rerender(<Parent directory={createDirectory('dir_1')} />);
+
+ await waitFor(() => expect(latest?.isPolling).toBe(true));
+ await waitFor(() => expect(getUsersSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+ });
+});

packages/shared/src/react/hooks/__tests__/useOrganizationEnterpriseConnectionTestRuns.spec.tsx

@@ -1,10 +1,12 @@
-import { act, renderHook, waitFor } from '@testing-library/react';
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { GetEnterpriseConnectionTestRunsParams } from '@/types/enterpriseConnectionTestRun';
 
 import { INTERNAL_STABLE_KEYS } from '../../stable-keys';
 import { createCacheKeys } from '../createCacheKeys';
+import type { UseOrganizationEnterpriseConnectionTestRunsReturn } from '../useOrganizationEnterpriseConnectionTestRuns';
 import { __internal_useOrganizationEnterpriseConnectionTestRuns } from '../useOrganizationEnterpriseConnectionTestRuns';
 import { createMockClerk, createMockQueryClient } from './mocks/clerk';
 import { wrapper } from './wrapper';
@@ -99,3 +101,69 @@ describe('useOrganizationEnterpriseConnectionTestRuns — revalidate invalidatio
  invalidateSpy.mockRestore();
  });
 });
+
+describe('useOrganizationEnterpriseConnectionTestRuns — polling arm scope', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('keeps polling armed by a child effect in the same commit the connection arrives', async () => {
+ getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+ let latest: UseOrganizationEnterpriseConnectionTestRunsReturn | undefined;
+
+ // Child effects run before parent effects, so this is the ordering a
+ // reset-in-effect implementation would silently cancel.
+ const Child = ({
+ enterpriseConnectionId,
+ revalidate,
+ }: {
+ enterpriseConnectionId: string | null;
+ revalidate: UseOrganizationEnterpriseConnectionTestRunsReturn['revalidate'];
+ }) => {
+ useEffect(() => {
+ if (enterpriseConnectionId) {
+ void revalidate();
+ }
+ }, [enterpriseConnectionId, revalidate]);
+ return null;
+ };
+
+ const Parent = ({ enterpriseConnectionId }: { enterpriseConnectionId: string | null }) => {
+ latest = __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 });
+ return (
+ <Child
+ enterpriseConnectionId={enterpriseConnectionId}
+ revalidate={latest.revalidate}
+ />
+ );
+ };
+
+ const { rerender } = render(<Parent enterpriseConnectionId={null} />);
+ expect(latest?.isPolling).toBe(false);
+
+ rerender(<Parent enterpriseConnectionId='ent_1' />);
+
+ await waitFor(() => expect(latest?.isPolling).toBe(true));
+ await waitFor(() => expect(getTestRunsSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+ });
+
+ it('disarms polling when the connection changes', async () => {
+ getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+ const { result, rerender } = renderHook(
+ ({ enterpriseConnectionId }: { enterpriseConnectionId: string }) =>
+ __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 }),
+ { wrapper, initialProps: { enterpriseConnectionId: 'ent_1' } },
+ );
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+ expect(result.current.isPolling).toBe(true);
+
+ rerender({ enterpriseConnectionId: 'ent_2' });
+ expect(result.current.isPolling).toBe(false);
+ });
+});

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

@@ -49,6 +49,16 @@ export type {
 } from './useOrganizationEnterpriseConnections';
 export { __internal_useOrganizationDomains } from './useOrganizationDomains';
 export type { UseOrganizationDomainsParams, UseOrganizationDomainsReturn } from './useOrganizationDomains';
+export { __internal_useOrganizationDirectorySync } from './useOrganizationDirectorySync';
+export type {
+ UseOrganizationDirectorySyncParams,
+ UseOrganizationDirectorySyncReturn,
+} from './useOrganizationDirectorySync';
+export { __internal_useOrganizationDirectorySyncUsers } from './useOrganizationDirectorySyncUsers';
+export type {
+ UseOrganizationDirectorySyncUsersParams,
+ UseOrganizationDirectorySyncUsersReturn,
+} from './useOrganizationDirectorySyncUsers';
 export { __internal_useOrganizationEnterpriseConnectionTestRuns } from './useOrganizationEnterpriseConnectionTestRuns';
 export type {
  UseOrganizationEnterpriseConnectionTestRunsParams,

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

@@ -0,0 +1,56 @@
+import { useMemo } from 'react';
+
+import type { GetDirectorySyncUsersParams } from '../../types/directorySync';
+import { INTERNAL_STABLE_KEYS } from '../stable-keys';
+import { createCacheKeys } from './createCacheKeys';
+
+/**
+ * @internal
+ */
+export function useOrganizationDirectorySyncCacheKeys(params: {
+ organizationId: string | null;
+ enterpriseConnectionId: string | null;
+}) {
+ const { organizationId, enterpriseConnectionId } = params;
+ return useMemo(() => {
+ return createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_KEY,
+ authenticated: Boolean(organizationId),
+ tracked: {
+ organizationId: organizationId ?? null,
+ enterpriseConnectionId: enterpriseConnectionId ?? null,
+ },
+ untracked: {
+ args: {},
+ },
+ });
+ }, [organizationId, enterpriseConnectionId]);
+}
+
+/**
+ * @internal
+ */
+export function useOrganizationDirectorySyncUsersCacheKeys(params: {
+ organizationId: string | null;
+ enterpriseConnectionId: string | null;
+ directoryId: string | null;
+ args: GetDirectorySyncUsersParams;
+}) {
+ const { organizationId, enterpriseConnectionId, directoryId, args } = params;
+ return useMemo(() => {
+ return createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_USERS_KEY,
+ authenticated: Boolean(organizationId),
+ tracked: {
+ organizationId: organizationId ?? null,
+ enterpriseConnectionId: enterpriseConnectionId ?? null,
+ directoryId: directoryId ?? null,
+ },
+ untracked: {
+ args,
+ },
+ });
+ // The args object is intentionally serialized via the consumer to keep stability.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [organizationId, enterpriseConnectionId, directoryId, JSON.stringify(args)]);
+}

packages/shared/src/react/hooks/__tests__/useOrganizationDirectorySync.spec.tsx

@@ -0,0 +1,92 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ClerkAPIResponseError } from '@/error';
+
+import { INTERNAL_STABLE_KEYS } from '../../stable-keys';
+import { createCacheKeys } from '../createCacheKeys';
+import { __internal_useOrganizationDirectorySync } from '../useOrganizationDirectorySync';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const directory = { id: 'dir_1', enterpriseConnectionId: 'ent_1' };
+const getDirectorySyncSpy = vi.fn((_enterpriseConnectionId: string) => Promise.resolve(directory));
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ queryClient: defaultQueryClient,
+ __internal_lastEmittedResources: {
+ user: null,
+ session: null,
+ organization: { id: 'org_1', getDirectorySync: getDirectorySyncSpy },
+ client: null,
+ },
+});
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const keysFor = (enterpriseConnectionId: string) =>
+ createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_KEY,
+ authenticated: true,
+ tracked: { organizationId: 'org_1', enterpriseConnectionId },
+ untracked: { args: {} },
+ });
+
+const renderDirectorySync = (enterpriseConnectionId: string | null = 'ent_1') =>
+ renderHook(() => __internal_useOrganizationDirectorySync({ enterpriseConnectionId }), { wrapper });
+
+describe('useOrganizationDirectorySync', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('resolves the directory for the connection', async () => {
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ expect(getDirectorySyncSpy).toHaveBeenCalledWith('ent_1');
+ expect(result.current.data).toBe(directory);
+ expect(result.current.error).toBeNull();
+ });
+
+ it('treats a 404 as "no directory yet" and resolves null instead of an error', async () => {
+ getDirectorySyncSpy.mockRejectedValueOnce(new ClerkAPIResponseError('Not found', { status: 404, data: [] }));
+
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ expect(result.current.data).toBeNull();
+ expect(result.current.error).toBeNull();
+ });
+
+ it('stays dormant without an enterprise connection id', () => {
+ const { result } = renderDirectorySync(null);
+
+ expect(getDirectorySyncSpy).not.toHaveBeenCalled();
+ expect(result.current.data).toBeUndefined();
+ });
+
+ it('revalidate refetches only this org+connection, leaving other connections cached', async () => {
+ const { queryKey: otherKey } = keysFor('ent_other');
+ defaultQueryClient.client.setQueryData(otherKey, { id: 'dir_other', enterpriseConnectionId: 'ent_other' });
+
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(getDirectorySyncSpy).toHaveBeenCalledTimes(1);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ expect(getDirectorySyncSpy).toHaveBeenCalledTimes(2);
+ expect(defaultQueryClient.client.getQueryState(otherKey)?.isInvalidated).toBe(false);
+ });
+});

packages/shared/src/react/hooks/__tests__/useOrganizationDirectorySyncUsers.spec.tsx

@@ -0,0 +1,121 @@
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { DirectorySyncResource } from '@/types/directorySync';
+
+import type { UseOrganizationDirectorySyncUsersReturn } from '../useOrganizationDirectorySyncUsers';
+import { __internal_useOrganizationDirectorySyncUsers } from '../useOrganizationDirectorySyncUsers';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const POLL_INTERVAL_MS = 20;
+
+const getUsersSpy = vi.fn(() => Promise.resolve({ data: [{ id: 'du_1' }], total_count: 1 }));
+
+const createDirectory = (id: string) =>
+ ({ id, enterpriseConnectionId: 'ent_1', getUsers: getUsersSpy }) as unknown as DirectorySyncResource;
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ queryClient: defaultQueryClient,
+ __internal_lastEmittedResources: {
+ user: null,
+ session: null,
+ organization: { id: 'org_1' },
+ client: null,
+ },
+});
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const renderUsers = (initialDirectory: DirectorySyncResource | null) =>
+ renderHook(
+ ({ directory }: { directory: DirectorySyncResource | null }) =>
+ __internal_useOrganizationDirectorySyncUsers({ directory, pollIntervalMs: POLL_INTERVAL_MS }),
+ { wrapper, initialProps: { directory: initialDirectory } },
+ );
+
+describe('useOrganizationDirectorySyncUsers', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('stays dormant without a directory', () => {
+ const { result } = renderUsers(null);
+
+ expect(getUsersSpy).not.toHaveBeenCalled();
+ expect(result.current.data).toBeUndefined();
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('polls while armed and stops on stopPolling', async () => {
+ const { result } = renderUsers(createDirectory('dir_1'));
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.isPolling).toBe(false);
+
+ act(() => result.current.startPolling());
+ expect(result.current.isPolling).toBe(true);
+ await waitFor(() => expect(getUsersSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+
+ act(() => result.current.stopPolling());
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('disarms polling when the directory identity changes', async () => {
+ const { result, rerender } = renderUsers(createDirectory('dir_1'));
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ act(() => result.current.startPolling());
+ expect(result.current.isPolling).toBe(true);
+
+ rerender({ directory: createDirectory('dir_2') });
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('keeps polling armed by a child effect in the same commit the directory arrives', async () => {
+ let latest: UseOrganizationDirectorySyncUsersReturn | undefined;
+
+ // Child effects run before parent effects, so this is the ordering a
+ // reset-in-effect implementation would silently cancel.
+ const Child = ({
+ directory,
+ startPolling,
+ }: {
+ directory: DirectorySyncResource | null;
+ startPolling: () => void;
+ }) => {
+ useEffect(() => {
+ if (directory) {
+ startPolling();
+ }
+ }, [directory, startPolling]);
+ return null;
+ };
+
+ const Parent = ({ directory }: { directory: DirectorySyncResource | null }) => {
+ latest = __internal_useOrganizationDirectorySyncUsers({ directory, pollIntervalMs: POLL_INTERVAL_MS });
+ return (
+ <Child
+ directory={directory}
+ startPolling={latest.startPolling}
+ />
+ );
+ };
+
+ const { rerender } = render(<Parent directory={null} />);
+ expect(latest?.isPolling).toBe(false);
+
+ rerender(<Parent directory={createDirectory('dir_1')} />);
+
+ await waitFor(() => expect(latest?.isPolling).toBe(true));
+ await waitFor(() => expect(getUsersSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+ });
+});

packages/shared/src/react/hooks/__tests__/useOrganizationEnterpriseConnectionTestRuns.spec.tsx

@@ -1,10 +1,12 @@
-import { act, renderHook, waitFor } from '@testing-library/react';
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { GetEnterpriseConnectionTestRunsParams } from '@/types/enterpriseConnectionTestRun';
 
 import { INTERNAL_STABLE_KEYS } from '../../stable-keys';
 import { createCacheKeys } from '../createCacheKeys';
+import type { UseOrganizationEnterpriseConnectionTestRunsReturn } from '../useOrganizationEnterpriseConnectionTestRuns';
 import { __internal_useOrganizationEnterpriseConnectionTestRuns } from '../useOrganizationEnterpriseConnectionTestRuns';
 import { createMockClerk, createMockQueryClient } from './mocks/clerk';
 import { wrapper } from './wrapper';
@@ -99,3 +101,69 @@ describe('useOrganizationEnterpriseConnectionTestRuns — revalidate invalidatio
  invalidateSpy.mockRestore();
  });
 });
+
+describe('useOrganizationEnterpriseConnectionTestRuns — polling arm scope', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('keeps polling armed by a child effect in the same commit the connection arrives', async () => {
+ getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+ let latest: UseOrganizationEnterpriseConnectionTestRunsReturn | undefined;
+
+ // Child effects run before parent effects, so this is the ordering a
+ // reset-in-effect implementation would silently cancel.
+ const Child = ({
+ enterpriseConnectionId,
+ revalidate,
+ }: {
+ enterpriseConnectionId: string | null;
+ revalidate: UseOrganizationEnterpriseConnectionTestRunsReturn['revalidate'];
+ }) => {
+ useEffect(() => {
+ if (enterpriseConnectionId) {
+ void revalidate();
+ }
+ }, [enterpriseConnectionId, revalidate]);
+ return null;
+ };
+
+ const Parent = ({ enterpriseConnectionId }: { enterpriseConnectionId: string | null }) => {
+ latest = __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 });
+ return (
+ <Child
+ enterpriseConnectionId={enterpriseConnectionId}
+ revalidate={latest.revalidate}
+ />
+ );
+ };
+
+ const { rerender } = render(<Parent enterpriseConnectionId={null} />);
+ expect(latest?.isPolling).toBe(false);
+
+ rerender(<Parent enterpriseConnectionId='ent_1' />);
+
+ await waitFor(() => expect(latest?.isPolling).toBe(true));
+ await waitFor(() => expect(getTestRunsSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+ });
+
+ it('disarms polling when the connection changes', async () => {
+ getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+ const { result, rerender } = renderHook(
+ ({ enterpriseConnectionId }: { enterpriseConnectionId: string }) =>
+ __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 }),
+ { wrapper, initialProps: { enterpriseConnectionId: 'ent_1' } },
+ );
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+ expect(result.current.isPolling).toBe(true);
+
+ rerender({ enterpriseConnectionId: 'ent_2' });
+ expect(result.current.isPolling).toBe(false);
+ });
+});

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

@@ -49,6 +49,16 @@ export type {
 } from './useOrganizationEnterpriseConnections';
 export { __internal_useOrganizationDomains } from './useOrganizationDomains';
 export type { UseOrganizationDomainsParams, UseOrganizationDomainsReturn } from './useOrganizationDomains';
+export { __internal_useOrganizationDirectorySync } from './useOrganizationDirectorySync';
+export type {
+ UseOrganizationDirectorySyncParams,
+ UseOrganizationDirectorySyncReturn,
+} from './useOrganizationDirectorySync';
+export { __internal_useOrganizationDirectorySyncUsers } from './useOrganizationDirectorySyncUsers';
+export type {
+ UseOrganizationDirectorySyncUsersParams,
+ UseOrganizationDirectorySyncUsersReturn,
+} from './useOrganizationDirectorySyncUsers';
 export { __internal_useOrganizationEnterpriseConnectionTestRuns } from './useOrganizationEnterpriseConnectionTestRuns';
 export type {
  UseOrganizationEnterpriseConnectionTestRunsParams,

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

@@ -0,0 +1,56 @@
+import { useMemo } from 'react';
+
+import type { GetDirectorySyncUsersParams } from '../../types/directorySync';
+import { INTERNAL_STABLE_KEYS } from '../stable-keys';
+import { createCacheKeys } from './createCacheKeys';
+
+/**
+ * @internal
+ */
+export function useOrganizationDirectorySyncCacheKeys(params: {
+ organizationId: string | null;
+ enterpriseConnectionId: string | null;
+}) {
+ const { organizationId, enterpriseConnectionId } = params;
+ return useMemo(() => {
+ return createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_KEY,
+ authenticated: Boolean(organizationId),
+ tracked: {
+ organizationId: organizationId ?? null,
+ enterpriseConnectionId: enterpriseConnectionId ?? null,
+ },
+ untracked: {
+ args: {},
+ },
+ });
+ }, [organizationId, enterpriseConnectionId]);
+}
+
+/**
+ * @internal
+ */
+export function useOrganizationDirectorySyncUsersCacheKeys(params: {
+ organizationId: string | null;
+ enterpriseConnectionId: string | null;
+ directoryId: string | null;
+ args: GetDirectorySyncUsersParams;
+}) {
+ const { organizationId, enterpriseConnectionId, directoryId, args } = params;
+ return useMemo(() => {
+ return createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_USERS_KEY,
+ authenticated: Boolean(organizationId),
+ tracked: {
+ organizationId: organizationId ?? null,
+ enterpriseConnectionId: enterpriseConnectionId ?? null,
+ directoryId: directoryId ?? null,
+ },
+ untracked: {
+ args,
+ },
+ });
+ // The args object is intentionally serialized via the consumer to keep stability.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [organizationId, enterpriseConnectionId, directoryId, JSON.stringify(args)]);
+}

packages/shared/src/react/hooks/__tests__/useOrganizationDirectorySync.spec.tsx

@@ -0,0 +1,92 @@
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { ClerkAPIResponseError } from '@/error';
+
+import { INTERNAL_STABLE_KEYS } from '../../stable-keys';
+import { createCacheKeys } from '../createCacheKeys';
+import { __internal_useOrganizationDirectorySync } from '../useOrganizationDirectorySync';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const directory = { id: 'dir_1', enterpriseConnectionId: 'ent_1' };
+const getDirectorySyncSpy = vi.fn((_enterpriseConnectionId: string) => Promise.resolve(directory));
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ queryClient: defaultQueryClient,
+ __internal_lastEmittedResources: {
+ user: null,
+ session: null,
+ organization: { id: 'org_1', getDirectorySync: getDirectorySyncSpy },
+ client: null,
+ },
+});
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const keysFor = (enterpriseConnectionId: string) =>
+ createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_KEY,
+ authenticated: true,
+ tracked: { organizationId: 'org_1', enterpriseConnectionId },
+ untracked: { args: {} },
+ });
+
+const renderDirectorySync = (enterpriseConnectionId: string | null = 'ent_1') =>
+ renderHook(() => __internal_useOrganizationDirectorySync({ enterpriseConnectionId }), { wrapper });
+
+describe('useOrganizationDirectorySync', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('resolves the directory for the connection', async () => {
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ expect(getDirectorySyncSpy).toHaveBeenCalledWith('ent_1');
+ expect(result.current.data).toBe(directory);
+ expect(result.current.error).toBeNull();
+ });
+
+ it('treats a 404 as "no directory yet" and resolves null instead of an error', async () => {
+ getDirectorySyncSpy.mockRejectedValueOnce(new ClerkAPIResponseError('Not found', { status: 404, data: [] }));
+
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ expect(result.current.data).toBeNull();
+ expect(result.current.error).toBeNull();
+ });
+
+ it('stays dormant without an enterprise connection id', () => {
+ const { result } = renderDirectorySync(null);
+
+ expect(getDirectorySyncSpy).not.toHaveBeenCalled();
+ expect(result.current.data).toBeUndefined();
+ });
+
+ it('revalidate refetches only this org+connection, leaving other connections cached', async () => {
+ const { queryKey: otherKey } = keysFor('ent_other');
+ defaultQueryClient.client.setQueryData(otherKey, { id: 'dir_other', enterpriseConnectionId: 'ent_other' });
+
+ const { result } = renderDirectorySync();
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(getDirectorySyncSpy).toHaveBeenCalledTimes(1);
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+
+ expect(getDirectorySyncSpy).toHaveBeenCalledTimes(2);
+ expect(defaultQueryClient.client.getQueryState(otherKey)?.isInvalidated).toBe(false);
+ });
+});

packages/shared/src/react/hooks/__tests__/useOrganizationDirectorySyncUsers.spec.tsx

@@ -0,0 +1,121 @@
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { DirectorySyncResource } from '@/types/directorySync';
+
+import type { UseOrganizationDirectorySyncUsersReturn } from '../useOrganizationDirectorySyncUsers';
+import { __internal_useOrganizationDirectorySyncUsers } from '../useOrganizationDirectorySyncUsers';
+import { createMockClerk, createMockQueryClient } from './mocks/clerk';
+import { wrapper } from './wrapper';
+
+const POLL_INTERVAL_MS = 20;
+
+const getUsersSpy = vi.fn(() => Promise.resolve({ data: [{ id: 'du_1' }], total_count: 1 }));
+
+const createDirectory = (id: string) =>
+ ({ id, enterpriseConnectionId: 'ent_1', getUsers: getUsersSpy }) as unknown as DirectorySyncResource;
+
+const defaultQueryClient = createMockQueryClient();
+
+const mockClerk = createMockClerk({
+ queryClient: defaultQueryClient,
+ __internal_lastEmittedResources: {
+ user: null,
+ session: null,
+ organization: { id: 'org_1' },
+ client: null,
+ },
+});
+
+vi.mock('../../contexts', () => ({
+ useAssertWrappedByClerkProvider: () => {},
+ useClerkInstanceContext: () => mockClerk,
+ useInitialStateContext: () => undefined,
+}));
+
+const renderUsers = (initialDirectory: DirectorySyncResource | null) =>
+ renderHook(
+ ({ directory }: { directory: DirectorySyncResource | null }) =>
+ __internal_useOrganizationDirectorySyncUsers({ directory, pollIntervalMs: POLL_INTERVAL_MS }),
+ { wrapper, initialProps: { directory: initialDirectory } },
+ );
+
+describe('useOrganizationDirectorySyncUsers', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('stays dormant without a directory', () => {
+ const { result } = renderUsers(null);
+
+ expect(getUsersSpy).not.toHaveBeenCalled();
+ expect(result.current.data).toBeUndefined();
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('polls while armed and stops on stopPolling', async () => {
+ const { result } = renderUsers(createDirectory('dir_1'));
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+ expect(result.current.isPolling).toBe(false);
+
+ act(() => result.current.startPolling());
+ expect(result.current.isPolling).toBe(true);
+ await waitFor(() => expect(getUsersSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+
+ act(() => result.current.stopPolling());
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('disarms polling when the directory identity changes', async () => {
+ const { result, rerender } = renderUsers(createDirectory('dir_1'));
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ act(() => result.current.startPolling());
+ expect(result.current.isPolling).toBe(true);
+
+ rerender({ directory: createDirectory('dir_2') });
+ expect(result.current.isPolling).toBe(false);
+ });
+
+ it('keeps polling armed by a child effect in the same commit the directory arrives', async () => {
+ let latest: UseOrganizationDirectorySyncUsersReturn | undefined;
+
+ // Child effects run before parent effects, so this is the ordering a
+ // reset-in-effect implementation would silently cancel.
+ const Child = ({
+ directory,
+ startPolling,
+ }: {
+ directory: DirectorySyncResource | null;
+ startPolling: () => void;
+ }) => {
+ useEffect(() => {
+ if (directory) {
+ startPolling();
+ }
+ }, [directory, startPolling]);
+ return null;
+ };
+
+ const Parent = ({ directory }: { directory: DirectorySyncResource | null }) => {
+ latest = __internal_useOrganizationDirectorySyncUsers({ directory, pollIntervalMs: POLL_INTERVAL_MS });
+ return (
+ <Child
+ directory={directory}
+ startPolling={latest.startPolling}
+ />
+ );
+ };
+
+ const { rerender } = render(<Parent directory={null} />);
+ expect(latest?.isPolling).toBe(false);
+
+ rerender(<Parent directory={createDirectory('dir_1')} />);
+
+ await waitFor(() => expect(latest?.isPolling).toBe(true));
+ await waitFor(() => expect(getUsersSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+ });
+});

packages/shared/src/react/hooks/__tests__/useOrganizationEnterpriseConnectionTestRuns.spec.tsx

@@ -1,10 +1,12 @@
-import { act, renderHook, waitFor } from '@testing-library/react';
+import { act, render, renderHook, waitFor } from '@testing-library/react';
+import React, { useEffect } from 'react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import type { GetEnterpriseConnectionTestRunsParams } from '@/types/enterpriseConnectionTestRun';
 
 import { INTERNAL_STABLE_KEYS } from '../../stable-keys';
 import { createCacheKeys } from '../createCacheKeys';
+import type { UseOrganizationEnterpriseConnectionTestRunsReturn } from '../useOrganizationEnterpriseConnectionTestRuns';
 import { __internal_useOrganizationEnterpriseConnectionTestRuns } from '../useOrganizationEnterpriseConnectionTestRuns';
 import { createMockClerk, createMockQueryClient } from './mocks/clerk';
 import { wrapper } from './wrapper';
@@ -99,3 +101,69 @@ describe('useOrganizationEnterpriseConnectionTestRuns — revalidate invalidatio
  invalidateSpy.mockRestore();
  });
 });
+
+describe('useOrganizationEnterpriseConnectionTestRuns — polling arm scope', () => {
+ beforeEach(() => {
+ vi.clearAllMocks();
+ defaultQueryClient.client.clear();
+ mockClerk.loaded = true;
+ });
+
+ it('keeps polling armed by a child effect in the same commit the connection arrives', async () => {
+ getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+ let latest: UseOrganizationEnterpriseConnectionTestRunsReturn | undefined;
+
+ // Child effects run before parent effects, so this is the ordering a
+ // reset-in-effect implementation would silently cancel.
+ const Child = ({
+ enterpriseConnectionId,
+ revalidate,
+ }: {
+ enterpriseConnectionId: string | null;
+ revalidate: UseOrganizationEnterpriseConnectionTestRunsReturn['revalidate'];
+ }) => {
+ useEffect(() => {
+ if (enterpriseConnectionId) {
+ void revalidate();
+ }
+ }, [enterpriseConnectionId, revalidate]);
+ return null;
+ };
+
+ const Parent = ({ enterpriseConnectionId }: { enterpriseConnectionId: string | null }) => {
+ latest = __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 });
+ return (
+ <Child
+ enterpriseConnectionId={enterpriseConnectionId}
+ revalidate={latest.revalidate}
+ />
+ );
+ };
+
+ const { rerender } = render(<Parent enterpriseConnectionId={null} />);
+ expect(latest?.isPolling).toBe(false);
+
+ rerender(<Parent enterpriseConnectionId='ent_1' />);
+
+ await waitFor(() => expect(latest?.isPolling).toBe(true));
+ await waitFor(() => expect(getTestRunsSpy.mock.calls.length).toBeGreaterThanOrEqual(3));
+ });
+
+ it('disarms polling when the connection changes', async () => {
+ getTestRunsSpy.mockImplementation(() => Promise.resolve({ data: [], total_count: 0 }));
+ const { result, rerender } = renderHook(
+ ({ enterpriseConnectionId }: { enterpriseConnectionId: string }) =>
+ __internal_useOrganizationEnterpriseConnectionTestRuns({ enterpriseConnectionId, pollIntervalMs: 20 }),
+ { wrapper, initialProps: { enterpriseConnectionId: 'ent_1' } },
+ );
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+ await act(async () => {
+ await result.current.revalidate();
+ });
+ expect(result.current.isPolling).toBe(true);
+
+ rerender({ enterpriseConnectionId: 'ent_2' });
+ expect(result.current.isPolling).toBe(false);
+ });
+});

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

@@ -49,6 +49,16 @@ export type {
 } from './useOrganizationEnterpriseConnections';
 export { __internal_useOrganizationDomains } from './useOrganizationDomains';
 export type { UseOrganizationDomainsParams, UseOrganizationDomainsReturn } from './useOrganizationDomains';
+export { __internal_useOrganizationDirectorySync } from './useOrganizationDirectorySync';
+export type {
+ UseOrganizationDirectorySyncParams,
+ UseOrganizationDirectorySyncReturn,
+} from './useOrganizationDirectorySync';
+export { __internal_useOrganizationDirectorySyncUsers } from './useOrganizationDirectorySyncUsers';
+export type {
+ UseOrganizationDirectorySyncUsersParams,
+ UseOrganizationDirectorySyncUsersReturn,
+} from './useOrganizationDirectorySyncUsers';
 export { __internal_useOrganizationEnterpriseConnectionTestRuns } from './useOrganizationEnterpriseConnectionTestRuns';
 export type {
  UseOrganizationEnterpriseConnectionTestRunsParams,

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

@@ -0,0 +1,56 @@
+import { useMemo } from 'react';
+
+import type { GetDirectorySyncUsersParams } from '../../types/directorySync';
+import { INTERNAL_STABLE_KEYS } from '../stable-keys';
+import { createCacheKeys } from './createCacheKeys';
+
+/**
+ * @internal
+ */
+export function useOrganizationDirectorySyncCacheKeys(params: {
+ organizationId: string | null;
+ enterpriseConnectionId: string | null;
+}) {
+ const { organizationId, enterpriseConnectionId } = params;
+ return useMemo(() => {
+ return createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_KEY,
+ authenticated: Boolean(organizationId),
+ tracked: {
+ organizationId: organizationId ?? null,
+ enterpriseConnectionId: enterpriseConnectionId ?? null,
+ },
+ untracked: {
+ args: {},
+ },
+ });
+ }, [organizationId, enterpriseConnectionId]);
+}
+
+/**
+ * @internal
+ */
+export function useOrganizationDirectorySyncUsersCacheKeys(params: {
+ organizationId: string | null;
+ enterpriseConnectionId: string | null;
+ directoryId: string | null;
+ args: GetDirectorySyncUsersParams;
+}) {
+ const { organizationId, enterpriseConnectionId, directoryId, args } = params;
+ return useMemo(() => {
+ return createCacheKeys({
+ stablePrefix: INTERNAL_STABLE_KEYS.ORGANIZATION_DIRECTORY_SYNC_USERS_KEY,
+ authenticated: Boolean(organizationId),
+ tracked: {
+ organizationId: organizationId ?? null,
+ enterpriseConnectionId: enterpriseConnectionId ?? null,
+ directoryId: directoryId ?? null,
+ },
+ untracked: {
+ args,
+ },
+ });
+ // The args object is intentionally serialized via the consumer to keep stability.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [organizationId, enterpriseConnectionId, directoryId, JSON.stringify(args)]);
+}