feat(react): add useHandleOAuthCallback hook

[joshuaellis]

Description

Adds useOAuthCallback, the OAuth counterpart to useHandleAuthCallback

[claude]

Claude finished @joshuaellis's task in 2m 12s —— View job

---

Review

Wiring matches useHandleAuthCallback exactly (createCallbackHook(handleOAuthCallback), sibling test shape, export added to sdk-react.ts), and the TSDoc claims check out against core: the isExchangingToken guard in oauthActions.ts runs synchronously before the first await, so the StrictMode single-flight claim holds, and re-running after a completed exchange does fail state validation into ERROR as documented.

Two things, both minor:

1. The documented example can't observe a failed token exchange — packages/react/src/hooks/auth/useHandleOAuthCallback.tsx:22-37

handleOAuthCallback only rejects when the instance isn't configured for OAuth (getOAuthOptions throws). Every other failure path — ?error= redirect, state mismatch, missing verifier, a failed /auth/oauth/token request — resolves with the cleaned URL and reports the failure by setting authState to ERROR (packages/core/src/auth/oauth/oauthActions.ts:158-232). A consumer copying the example gets a truthy cleanedUrl, calls history.replaceState, and renders "Completing sign-in…" forever with .catch(console.error) never firing.

Worth one sentence in @remarks pointing at useAuthState / AuthStateType.ERROR as the way to detect failure, since the promise result alone can't distinguish success from failure.

Fix this →

2. Changeset bumps @sanity/sdk minor with no core change in this PR — .changeset/oauth-usehandlecallback.md:2

This PR touches packages/react only. The sibling changeset (oauth-usetokens.md) lists both packages because that PR did change core. Harmless in practice — other pending changesets already bump core minor — but the entry will show up in core's changelog describing a React-only hook. Dropping the '@sanity/sdk': minor line is more accurate.

Checks not run

pnpm install was blocked in this sandbox, so I couldn't run pnpm test, pnpm ts:check, or pnpm fallow audit locally. CI coverage already reports 100% on the new file.

· branch [`feat/SDK-2419`](https://github.com/sanity-io/sdk/tree/feat/SDK-2419)

[github-actions]

Bundle Stats

✅ No significant changes.

All scenario measurements (8)

🗺️ @sanity/sdk / @sanity/sdk · @sanity/sdk / @sanity/sdk/_internal · @sanity/sdk / @sanity/sdk/agent · @sanity/sdk / @sanity/sdk/comlink · @sanity/sdk / @sanity/sdk/dashboard · @sanity/sdk-react / @sanity/sdk-react · @sanity/sdk-react / @sanity/sdk-react/dashboard · @sanity/sdk-react / @sanity/sdk-react/dashboard/_internal · Artifacts

Scenario	Kind	Bundle (raw / gzip)	Gzip change	Import time	Import change
⚪ @sanity/sdk / @sanity/sdk	export	1.14 MB / 259.5 KB	None	256 ms	-4 ms, -1.6%
⚪ @sanity/sdk / @sanity/sdk/_internal	export	599.2 KB / 137.0 KB	None	188 ms	-0 ms, -0.0%
⚪ @sanity/sdk / @sanity/sdk/agent	export	414.5 KB / 90.9 KB	None	172 ms	+2 ms, +1.0%
⚪ @sanity/sdk / @sanity/sdk/comlink	export	260.2 KB / 60.6 KB	None	186 ms	+1 ms, +0.7%
⚪ @sanity/sdk / @sanity/sdk/dashboard	export	105.0 KB / 23.2 KB	None	169 ms	+2 ms, +1.2%
⚪ @sanity/sdk-react / @sanity/sdk-react	export	1.42 MB / 334.2 KB	+22 B, +0.0%	303 ms	-1 ms, -0.2%
⚪ @sanity/sdk-react / @sanity/sdk-react/dashboard	export	827.1 KB / 189.1 KB	None	306 ms	+2 ms, +0.6%
⚪ @sanity/sdk-react / @sanity/sdk-react/dashboard/_internal	export	107.8 KB / 23.7 KB	None	188 ms	-3 ms, -1.8%

Significant means at least 1.0 KB and 1% gzip, or at least 5 ms and 10% import time.

[github-actions]

📚 TypeDoc Generation Result

✅ TypeDoc generated successfully!

• JSON file size: 3.2M
• Total exports: 448
• Artifact: typedoc-html-pr-1216
• HTML docs preview: Download artifact

The package TypeDoc JSON files and combined HTML site have been generated successfully.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🟢	Lines	97.34% (🎯 94%)	5893 / 6054
🟢	Statements	96.04% (🎯 93%)	6409 / 6673
🟢	Functions	97.34% (🎯 94%)	1763 / 1811
🟢	Branches	89.97% (🎯 86%)	3402 / 3781

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/react/src/hooks/auth/useHandleOAuthCallback.tsx	100%	100%	100%	100%

Generated in workflow #6457 for commit 0d90453 by the Vitest Coverage Report Action

[joshuaellis]

Both actioned: renamed to useHandleOAuthCallback to match useHandleAuthCallback, and dropped the AuthBoundary sentences from the TSDoc; they return in #1223 where handleAuthCallback starts delegating to the OAuth path.