feat(backend): Introduce OrganizationRoleAPI (#2177)

* feat(backend): Introduce OrganizationRoleAPI

* test(backend): Update exports.test.ts

* test(clerk-sdk-node): Update exports

* test(nextjs): Update exports.test.ts.snap

* feat(backend): Address PR comments

* chore(backend): Rename OrganizationRole to Role

.changeset/cold-comics-serve.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Add OrganizationRoleAPI for CRUD operations regarding instance level organization roles.

packages/backend/src/api/endpoints/OrganizationRoleApi.ts

@@ -0,0 +1,138 @@
+import { joinPaths } from '../../util/path';
+import type { DeletedObject, Role } from '../resources';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/organizations_roles';
+
+type GetRoleListParams = {
+  limit?: number;
+  offset?: number;
+  query?: string;
+  order_by?: string;
+};
+
+type CreateParams = {
+  /**
+   * A name of a role in a readable friendly format.
+   * F.e. `Teacher` or `Administrator`
+   */
+  name: string;
+
+  /**
+   * A unique identifier that represents the role.
+   * F.e. `org:administrator`
+   */
+  key: string;
+
+  /**
+   * A brief description of what the role represents or its intended use.
+   */
+  description: string;
+
+  /**
+   * An array of permission ids that will be assigned to this role.
+   */
+  permissions: string[];
+};
+
+type GetOrganizationRoleParams = { roleId: string };
+
+type UpdateParams = {
+  /**
+   * A name of a role in a readable friendly format.
+   * F.e. `Teacher` or `Administrator`
+   * Passing undefined has no effect to the existing value.
+   */
+  name?: string;
+
+  /**
+   * A unique identifier that represents the role.
+   * F.e. `org:administrator`
+   * Passing undefined has no effect to the existing value.
+   */
+  key?: string;
+
+  /**
+   * A brief description of what the role represents or its intended use.
+   * Passing undefined has no effect to the existing value.
+   */
+  description?: string;
+
+  /**
+   * An array of permission ids that will be assigned to this role.
+   * Passing undefined has no effect to the permission that already exist.
+   * Passing an empty array will override the existing permissions.
+   */
+  permissions?: string[];
+};
+
+type RemovePermissionParams = {
+  permissionId: string;
+  roleId: string;
+};
+
+type AssignPermissionParams = RemovePermissionParams;
+
+export class OrganizationRoleAPI extends AbstractAPI {
+  public async getOrganizationRoleList(params?: GetRoleListParams) {
+    return this.request<Role[]>({
+      method: 'GET',
+      path: basePath,
+      queryParams: params,
+    });
+  }
+
+  public async createOrganizationRole(params: CreateParams) {
+    return this.request<Role>({
+      method: 'POST',
+      path: basePath,
+      bodyParams: params,
+    });
+  }
+
+  public async getOrganizationRole(params: GetOrganizationRoleParams) {
+    this.requireId(params.roleId);
+
+    return this.request<Role>({
+      method: 'GET',
+      path: joinPaths(basePath, params.roleId),
+    });
+  }
+
+  public async updateOrganizationRole(roleId: string, params: UpdateParams) {
+    this.requireId(roleId);
+    return this.request<Role>({
+      method: 'PATCH',
+      path: joinPaths(basePath, roleId),
+      bodyParams: params,
+    });
+  }
+
+  public async deleteOrganizationRole(roleId: string) {
+    this.requireId(roleId);
+    return this.request<DeletedObject>({
+      method: 'DELETE',
+      path: joinPaths(basePath, roleId),
+    });
+  }
+
+  public async assignPermissionToRole(params: AssignPermissionParams) {
+    const { roleId, permissionId } = params;
+    this.requireId(roleId);
+    this.requireId(permissionId);
+    return this.request<Role>({
+      method: 'POST',
+      path: joinPaths(basePath, roleId, 'permission', permissionId),
+    });
+  }
+
+  public async removePermissionFromRole(params: RemovePermissionParams) {
+    const { roleId, permissionId } = params;
+    this.requireId(roleId);
+    this.requireId(permissionId);
+    return this.request<Role>({
+      method: 'DELETE',
+      path: joinPaths(basePath, roleId, 'permission', permissionId),
+    });
+  }
+}

packages/backend/src/api/endpoints/index.ts

@@ -7,6 +7,7 @@ export * from './EmailApi';
 export * from './InterstitialApi';
 export * from './InvitationApi';
 export * from './OrganizationApi';
+export * from './OrganizationRoleApi';
 export * from './OrganizationPermissionApi';
 export * from './PhoneNumberApi';
 export * from './RedirectUrlApi';

packages/backend/src/api/factory.ts

@@ -8,6 +8,7 @@ import {
   InvitationAPI,
   OrganizationAPI,
   OrganizationPermissionAPI,
+  OrganizationRoleAPI,
   PhoneNumberAPI,
   RedirectUrlAPI,
   SessionAPI,
@@ -30,6 +31,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
     interstitial: new InterstitialAPI(request),
     invitations: new InvitationAPI(request),
     organizations: new OrganizationAPI(request),
+    organizationRoles: new OrganizationRoleAPI(request),
     organizationPermissions: new OrganizationPermissionAPI(request),
     phoneNumbers: new PhoneNumberAPI(request),
     redirectUrls: new RedirectUrlAPI(request),

packages/backend/src/api/resources/JSON.ts

@@ -21,6 +21,7 @@ export enum ObjectType {
   Organization = 'organization',
   OrganizationInvitation = 'organization_invitation',
   OrganizationMembership = 'organization_membership',
+  Role = 'role',
   Permission = 'permission',
   PhoneNumber = 'phone_number',
   RedirectUrl = 'redirect_url',
@@ -174,6 +175,16 @@ export interface OrganizationMembershipPublicUserDataJSON {
   user_id: string;
 }
 
+export interface RoleJSON extends ClerkResourceJSON {
+  object: ObjectType.Role;
+  name: string;
+  key: string;
+  description: string;
+  permissions: PermissionJSON[];
+  created_at: number;
+  updated_at: number;
+}
+
 export interface PermissionJSON extends ClerkResourceJSON {
   object: ObjectType.Permission;
   id: string;

packages/backend/src/api/resources/Role.ts

@@ -0,0 +1,26 @@
+import type { RoleJSON } from './JSON';
+import { Permission } from './Permission';
+
+export class Role {
+  constructor(
+    readonly id: string,
+    readonly name: string,
+    readonly key: string,
+    readonly description: string,
+    readonly permissions: Permission[] = [],
+    readonly createdAt: number,
+    readonly updatedAt: number,
+  ) {}
+
+  static fromJSON(data: RoleJSON): Role {
+    return new Role(
+      data.id,
+      data.name,
+      data.key,
+      data.description,
+      (data.permissions || []).map(x => Permission.fromJSON(x)),
+      data.created_at,
+      data.updated_at,
+    );
+  }
+}

packages/backend/src/api/resources/index.ts

@@ -22,6 +22,7 @@ export * from './Invitation';
 export * from './JSON';
 export * from './OauthAccessToken';
 export * from './Organization';
+export * from './Role';
 export * from './Permission';
 export * from './OrganizationInvitation';
 export * from './OrganizationMembership';

packages/backend/src/exports.test.ts

@@ -27,6 +27,7 @@ export default (QUnit: QUnit) => {
         'Permission',
         'PhoneNumber',
         'RedirectUrl',
+        'Role',
         'SMSMessage',
         'Session',
         'SignInToken',

packages/nextjs/src/server/__tests__/__snapshots__/exports.test.ts.snap

@@ -21,6 +21,7 @@ exports[`/server public exports should not include a breaking change 1`] = `
   "Permission",
   "PhoneNumber",
   "RedirectUrl",
+  "Role",
   "SMSMessage",
   "Session",
   "SignInToken",

packages/sdk-node/src/__tests__/__snapshots__/exports.test.ts.snap

@@ -23,6 +23,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
   "Permission",
   "PhoneNumber",
   "RedirectUrl",
+  "Role",
   "SMSMessage",
   "Session",
   "SignInToken",
@@ -54,6 +55,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
   "loadInterstitialFromLocal",
   "makeAuthObjectSerializable",
   "organizationPermissions",
+  "organizationRoles",
   "organizations",
   "phoneNumbers",
   "prunePrivateMetadata",

packages/sdk-node/src/index.ts

@@ -26,6 +26,7 @@ const {
   emails,
   invitations,
   organizations,
+  organizationRoles,
   organizationPermissions,
   clients,
   allowlistIdentifiers,
@@ -40,6 +41,7 @@ export {
   emails,
   invitations,
   organizations,
+  organizationRoles,
   organizationPermissions,
   phoneNumbers,
   sessions,