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

[kalafut]

Description

Part 2 of 4 of the self-serve Directory Sync stack. Stacked on jim/dir-sync-1-resource. This change depends on the first PR and the stack will be squashed on merge.

Adds the internal react-query hooks __internal_useOrganizationDirectorySync and __internal_useOrganizationDirectorySyncUsers. Mutations go through the loaded DirectorySync resource, so they resolve undefined until the directory has loaded. The users hook takes the directory resource itself and stays dormant while it is nullish; it polls while armed via startPolling, so the wizard's test step doubles as a recent-activity feed.

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

✎

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4adb710

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clerk-js-sandbox	Ready	Preview	Sep 1, 2026 11:35pm UTC
swingset	Ready	Preview	Sep 1, 2026 11:35pm UTC

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9591

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9591

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9591

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9591

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9591

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9591

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9591

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9591

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9591

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9591

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9591

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9591

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9591

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9591

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9591

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9591

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9591

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9591

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9591

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9591

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9591

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9591

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9591

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9591

commit: 4adb710

[github-actions]

API Changes Report

Generated by Break Check on 2026-09-01T23:38:56.339Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	1
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	4

---

@clerk/shared

Current version: 4.30.2
Recommended bump: MINOR → 4.31.0

Subpath ./react

🟢 Additions (4)

Added: UseOrganizationDirectorySyncParams

+ type UseOrganizationDirectorySyncParams = {
+   enterpriseConnectionId: string | null;
+   enabled?: boolean;
+ };

Added type alias UseOrganizationDirectorySyncParams

Added: UseOrganizationDirectorySyncReturn

+ type UseOrganizationDirectorySyncReturn = {
+   data: DirectorySyncResource | null | undefined;
+   error: Error | null;
+   isLoading: boolean;
+   isFetching: boolean;
+   createDirectorySync: (params?: CreateDirectorySyncParams) => Promise<DirectorySyncResource | undefined>; /** Resolves `undefined` until `data` has loaded, since the mutations act on the loaded directory. */
+   updateDirectorySync: (params: UpdateDirectorySyncParams) => Promise<DirectorySyncResource | undefined>;
+   rotateDirectorySyncToken: () => Promise<DirectorySyncResource | undefined>;
+   deleteDirectorySync: () => Promise<DeletedObjectResource | undefined>;
+   revalidate: () => Promise<void>;
+ };

Added type alias UseOrganizationDirectorySyncReturn

Added: UseOrganizationDirectorySyncUsersParams

+ type UseOrganizationDirectorySyncUsersParams = {
+   directory: DirectorySyncResource | null | undefined;
+   params?: GetDirectorySyncUsersParams;
+   pollIntervalMs?: number;
+   enabled?: boolean;
+   keepPreviousData?: boolean;
+ };

Added type alias UseOrganizationDirectorySyncUsersParams

Added: UseOrganizationDirectorySyncUsersReturn

+ type UseOrganizationDirectorySyncUsersReturn = {
+   data: DirectorySyncUserResource[] | undefined;
+   totalCount: number | undefined;
+   error: Error | null;
+   isLoading: boolean;
+   isFetching: boolean;
+   isPolling: boolean;
+   startPolling: () => void;
+   stopPolling: () => void;
+   revalidate: () => Promise<void>;
+ };

Added type alias UseOrganizationDirectorySyncUsersReturn

---

Report generated by Break Check

_{Last ran on 4adb710.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Team

Run ID: 78b7b157-96c1-4659-85e5-0d1f2cf46fb6

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}