feat(backend): Introduce OrganizationRoleAPI

.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,98 @@
+import { joinPaths } from '../../util/path';
+import type { DeletedObject } from '../resources';
+import type { OrganizationRole } from '../resources/OrganizationRole';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/organizations_roles';
+
+type GetOrganizationRoleListParams = {
+  limit?: number;
+  offset?: number;
+};
+
+type CreateParams = {
+  name: string;
+  key: string;
+  description: string;
+  permissions: string[];
+};
+
+type GetOrganizationRoleParams = { roleId: string };
+
+type UpdateParams = {
+  name?: string;
+  description?: string;
+  //TODO(@pantelis): Will this override or union ?
+  permissions?: string[];
+};
+
+type RemovePermissionParams = {
+  permissionId: string;
+  roleId: string;
+};
+
+type AssignPermissionParams = RemovePermissionParams;
+
+export class OrganizationRoleAPI extends AbstractAPI {
+  public async getOrganizationRoleList(params?: GetOrganizationRoleListParams) {
+    return this.request<OrganizationRole[]>({
+      method: 'GET',
+      path: basePath,
+      queryParams: params,
+    });
+  }
+
+  public async createOrganizationRole(params: CreateParams) {
+    return this.request<OrganizationRole>({
+      method: 'POST',
+      path: basePath,
+      bodyParams: params,
+    });
+  }
+
+  public async getOrganizationRole(params: GetOrganizationRoleParams) {
+    this.requireId(params.roleId);
+
+    return this.request<OrganizationRole>({
+      method: 'GET',
+      path: joinPaths(basePath, params.roleId),
+    });
+  }
+
+  public async updateOrganizationRole(roleId: string, params: UpdateParams) {
+    this.requireId(roleId);
+    return this.request<OrganizationRole>({
+      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<OrganizationRole>({
+      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<OrganizationRole>({
+      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 './PhoneNumberApi';
 export * from './RedirectUrlApi';
 export * from './SessionApi';

packages/backend/src/api/factory.ts

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

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

@@ -20,6 +20,7 @@ export enum ObjectType {
   Organization = 'organization',
   OrganizationInvitation = 'organization_invitation',
   OrganizationMembership = 'organization_membership',
+  Role = 'role',
   PhoneNumber = 'phone_number',
   RedirectUrl = 'redirect_url',
   Session = 'session',
@@ -172,6 +173,16 @@ export interface OrganizationMembershipPublicUserDataJSON {
   user_id: string;
 }
 
+export interface OrganizationRoleJSON extends ClerkResourceJSON {
+  object: ObjectType.Role;
+  name: string;
+  key: string;
+  description: string;
+  permissions: string[];
+  created_at: number;
+  updated_at: number;
+}
+
 export interface PhoneNumberJSON extends ClerkResourceJSON {
   object: ObjectType.PhoneNumber;
   phone_number: string;

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

@@ -0,0 +1,25 @@
+import type { OrganizationRoleJSON } from './JSON';
+
+export class OrganizationRole {
+  constructor(
+    readonly id: string,
+    readonly name: string,
+    readonly key: string,
+    readonly description: string,
+    readonly permissions: string[],
+    readonly createdAt: number,
+    readonly updatedAt: number,
+  ) {}
+
+  static fromJSON(data: OrganizationRoleJSON): OrganizationRole {
+    return new OrganizationRole(
+      data.id,
+      data.name,
+      data.key,
+      data.description,
+      data.permissions,
+      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 './OrganizationRole';
 export * from './OrganizationInvitation';
 export * from './OrganizationMembership';
 export * from './PhoneNumber';