fix(*): improve role autocomplete for server-side has()

[bradlocking]

Description

Server-side has({ role }) and auth.protect({ role }) did not offer IDE string-literal completions for custom Roles defined via ClerkAuthorization, even though the values were type-checked correctly. Permission checks already completed because they go through a generic type parameter.

This change adds an optional Role generic (R) alongside the existing Permission generic (P) on CheckAuthorizationFromSessionClaims / CheckAuthorizationParamsFromSessionClaims, and mirrors it on auth.protect() in @clerk/nextjs. Defaults keep the change backwards-compatible.

Verified locally: with a custom ClerkAuthorization, has({ role: "|" }) now suggests Role literals the same way permission does.

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]

🦋 Changeset detected

Latest commit: 6812d75

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 23 packages

Name	Type
@clerk/shared	Patch
@clerk/nextjs	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/swingset	Patch

Not sure what this means? Click here to learn what changesets are.

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

[vercel]

@bradlocking is attempting to deploy a commit to the Clerk Production Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: 4bf491a8-08a8-4494-b377-a241edab3b8a

📥 Commits

Reviewing files that changed from the base of the PR and between 1447302 and 6812d75.

📒 Files selected for processing (4)

• .changeset/has-role-autocomplete.md
• packages/nextjs/src/server/protect.ts
• packages/shared/src/types/__tests__/CheckAuthorizationFromSessionClaims.type.spec.ts
• packages/shared/src/types/session.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• clerk/clerk_go (manual)
• clerk/dashboard (manual)
• clerk/accounts (manual)
• clerk/backoffice (manual)
• clerk/clerk (manual)
• clerk/clerk-docs (manual)
• clerk/cloudflare-workers (manual)

---

📝 Walkthrough

Walkthrough

The shared session-claims authorization types now accept a generic custom role key and use it for the role parameter. Type tests cover role-only, permission-only, invalid combined, and explicit generic cases. The Next.js AuthProtect overload now accepts and forwards the role-key generic. A changeset documents the update.

Estimated code review effort: 2 (Simple) | ~10 minutes

Mergeability Score: ⚪ Minimal · up to 6812d

This localized type-autocomplete change is merge-ready after normal checks and review; no actionable merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the bug fix for role autocomplete in server-side has(), which matches the main change.
Description check	✅ Passed	The description directly explains the role autocomplete issue, the generic type changes, affected APIs, and backward compatibility.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

Warning

Review ran into problems

🔥 Problems

Repository analysis: Couldn't refresh clerk/javascript clone - clone failed: Clone operation failed: Stream initialization permanently failed: 14 UNAVAILABLE: read ECONNRESET

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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