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

.changeset/has-role-autocomplete.md

@@ -0,0 +1,8 @@
+---
+'@clerk/shared': patch
+'@clerk/nextjs': patch
+---
+
+Fix IDE autocomplete for custom Organization Roles in server-side `has({ role })` and `auth.protect({ role })`.
+
+Previously, defining roles via `ClerkAuthorization` typed the values correctly but editors often failed to suggest Role literals inside `has({ role: "…" })`, while Permission suggestions already worked. Role checks now use the same generic typing path as Permissions so Role completions appear as expected.

packages/nextjs/src/server/protect.ts

@@ -14,6 +14,7 @@ import type {
   CheckAuthorizationParamsWithCustomPermissions,
   CheckAuthorizationWithCustomPermissions,
   OrganizationCustomPermissionKey,
+  OrganizationCustomRoleKey,
 } from '@clerk/shared/types';
 
 import { constants as nextConstants } from '../constants';
@@ -43,8 +44,8 @@ export interface AuthProtect {
    * auth.protect({ permission: 'org:admin:example1' });
    * auth.protect({ role: 'admin' });
    */
-  <P extends OrganizationCustomPermissionKey>(
-    params?: CheckAuthorizationParamsFromSessionClaims<P>,
+  <P extends OrganizationCustomPermissionKey, R extends OrganizationCustomRoleKey = OrganizationCustomRoleKey>(
+    params?: CheckAuthorizationParamsFromSessionClaims<P, R>,
     options?: AuthProtectOptions,
   ): Promise<SignedInAuthObject>;
 

packages/shared/src/types/__tests__/CheckAuthorizationFromSessionClaims.type.spec.ts

@@ -0,0 +1,44 @@
+import { describe, expectTypeOf, it } from 'vitest';
+
+import type { OrganizationCustomPermissionKey, OrganizationCustomRoleKey } from '../organizationMembership';
+import type { CheckAuthorizationFromSessionClaims, CheckAuthorizationParamsFromSessionClaims } from '../session';
+
+type ParamsOfHas = Parameters<CheckAuthorizationFromSessionClaims>[0];
+
+describe('CheckAuthorizationFromSessionClaims', () => {
+  it('has({}) is allowed', () => {
+    expectTypeOf({} as const).toMatchTypeOf<ParamsOfHas>();
+  });
+
+  it('has({ role }) is allowed', () => {
+    expectTypeOf({ role: 'org:admin' }).toMatchTypeOf<ParamsOfHas>();
+  });
+
+  it('has({ permission }) is allowed', () => {
+    expectTypeOf({
+      permission: 'org:feature:action',
+    }).toMatchTypeOf<ParamsOfHas>();
+  });
+
+  it('has({ role, permission }) is NOT allowed', () => {
+    expectTypeOf({
+      role: 'org:admin',
+      permission: 'org:feature:action',
+    }).not.toMatchTypeOf<ParamsOfHas>();
+  });
+
+  it('accepts an explicit Role type parameter', () => {
+    type RoleParams = CheckAuthorizationParamsFromSessionClaims<OrganizationCustomPermissionKey, 'org:admin'>;
+    expectTypeOf({ role: 'org:admin' as const }).toMatchTypeOf<RoleParams>();
+    expectTypeOf({
+      role: 'org:member' as const,
+    }).not.toMatchTypeOf<RoleParams>();
+  });
+
+  it('accepts an explicit Permission type parameter', () => {
+    type PermissionParams = CheckAuthorizationParamsFromSessionClaims<'org:reports:read', OrganizationCustomRoleKey>;
+    expectTypeOf({
+      permission: 'org:reports:read' as const,
+    }).toMatchTypeOf<PermissionParams>();
+  });
+});

packages/shared/src/types/session.ts

@@ -148,19 +148,25 @@ type CheckAuthorizationParams = WithReverification<
  * System Permissions are not allowed since they are not included
  * in session claims and cannot be verified on the server side.
  */
-export type CheckAuthorizationFromSessionClaims = <P extends OrganizationCustomPermissionKey>(
-  isAuthorizedParams: CheckAuthorizationParamsFromSessionClaims<P>,
+export type CheckAuthorizationFromSessionClaims = <
+  P extends OrganizationCustomPermissionKey,
+  R extends OrganizationCustomRoleKey = OrganizationCustomRoleKey,
+>(
+  isAuthorizedParams: CheckAuthorizationParamsFromSessionClaims<P, R>,
 ) => boolean;
 
 /**
  * @interface
  */
-export type CheckAuthorizationParamsFromSessionClaims<P extends OrganizationCustomPermissionKey> = WithReverification<
+export type CheckAuthorizationParamsFromSessionClaims<
+  P extends OrganizationCustomPermissionKey,
+  R extends OrganizationCustomRoleKey = OrganizationCustomRoleKey,
+> = WithReverification<
   | {
       /**
        * The [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) to check for.
        */
-      role: OrganizationCustomRoleKey;
+      role: R;
       /**
        * The [Permission](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) to check for.
        */