feat(backend): Introduce OrganizationPermissionAPI (#2178)

.changeset/swift-rocks-nail.md

@@ -0,0 +1,7 @@
+---
+'@clerk/clerk-sdk-node': patch
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+---
+
+Add OrganizationPermissionAPI for CRUD operations regarding instance level organization permissions.

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

@@ -0,0 +1,69 @@
+import { joinPaths } from '../../util/path';
+import type { DeletedObject, Permission } from '../resources';
+import { AbstractAPI } from './AbstractApi';
+
+const basePath = '/organizations_permissions';
+
+type GetOrganizationPermissionListParams = {
+  limit?: number;
+  offset?: number;
+  query?: string;
+  orderBy?: string;
+};
+
+type CreateParams = {
+  name: string;
+  key: string;
+  description: string;
+};
+
+type GetOrganizationPermissionParams = { permissionId: string };
+
+type UpdateParams = {
+  name?: string;
+  key?: string;
+  description?: string;
+};
+
+export class OrganizationPermissionAPI extends AbstractAPI {
+  public async getOrganizationPermissionList(params?: GetOrganizationPermissionListParams) {
+    return this.request<Permission[]>({
+      method: 'GET',
+      path: basePath,
+      queryParams: params,
+    });
+  }
+
+  public async createOrganizationPermission(params: CreateParams) {
+    return this.request<Permission>({
+      method: 'POST',
+      path: basePath,
+      bodyParams: params,
+    });
+  }
+
+  public async getOrganizationPermission(params: GetOrganizationPermissionParams) {
+    this.requireId(params.permissionId);
+
+    return this.request<Permission>({
+      method: 'GET',
+      path: joinPaths(basePath, params.permissionId),
+    });
+  }
+
+  public async updateOrganizationPermission(permissionId: string, params: UpdateParams) {
+    this.requireId(permissionId);
+    return this.request<Permission>({
+      method: 'PATCH',
+      path: joinPaths(basePath, permissionId),
+      bodyParams: params,
+    });
+  }
+
+  public async deleteOrganizationPermission(permissionId: string) {
+    return this.request<DeletedObject>({
+      method: 'DELETE',
+      path: joinPaths(basePath, 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 './OrganizationPermissionApi';
 export * from './PhoneNumberApi';
 export * from './RedirectUrlApi';
 export * from './SessionApi';

packages/backend/src/api/factory.ts

@@ -7,6 +7,7 @@ import {
   InterstitialAPI,
   InvitationAPI,
   OrganizationAPI,
+  OrganizationPermissionAPI,
   PhoneNumberAPI,
   RedirectUrlAPI,
   SessionAPI,
@@ -21,7 +22,6 @@ export type ApiClient = ReturnType<typeof createBackendApiClient>;
 
 export function createBackendApiClient(options: CreateBackendApiOptions) {
   const request = buildRequest(options);
-
   return {
     allowlistIdentifiers: new AllowlistIdentifierAPI(request),
     clients: new ClientAPI(request),
@@ -30,6 +30,7 @@ export function createBackendApiClient(options: CreateBackendApiOptions) {
     interstitial: new InterstitialAPI(request),
     invitations: new InvitationAPI(request),
     organizations: new OrganizationAPI(request),
+    organizationPermissions: new OrganizationPermissionAPI(request),
     phoneNumbers: new PhoneNumberAPI(request),
     redirectUrls: new RedirectUrlAPI(request),
     sessions: new SessionAPI(request),

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

@@ -20,6 +20,11 @@ export type OAuthStrategy = `oauth_${OAuthProvider}`;
 
 export type OrganizationInvitationStatus = 'pending' | 'accepted' | 'revoked';
 
+export type PermissionType = 'system' | 'user';
+
+/**
+ * @deprecated In the next major release this type will change to string
+ */
 export type OrganizationMembershipRole = 'basic_member' | 'guest_member' | 'admin';
 
 export type SignInStatus = 'needs_identifier' | 'needs_factor_one' | 'needs_factor_two' | 'complete';

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

@@ -2,6 +2,7 @@ import type {
   InvitationStatus,
   OrganizationInvitationStatus,
   OrganizationMembershipRole,
+  PermissionType,
   SignInStatus,
   SignUpAttributeRequirements,
   SignUpStatus,
@@ -20,6 +21,7 @@ export enum ObjectType {
   Organization = 'organization',
   OrganizationInvitation = 'organization_invitation',
   OrganizationMembership = 'organization_membership',
+  Permission = 'permission',
   PhoneNumber = 'phone_number',
   RedirectUrl = 'redirect_url',
   Session = 'session',
@@ -172,6 +174,17 @@ export interface OrganizationMembershipPublicUserDataJSON {
   user_id: string;
 }
 
+export interface PermissionJSON extends ClerkResourceJSON {
+  object: ObjectType.Permission;
+  id: string;
+  name: string;
+  key: string;
+  description: string;
+  type: PermissionType;
+  created_at: number;
+  updated_at: number;
+}
+
 export interface PhoneNumberJSON extends ClerkResourceJSON {
   object: ObjectType.PhoneNumber;
   phone_number: string;

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

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

packages/backend/src/exports.test.ts

@@ -24,6 +24,7 @@ export default (QUnit: QUnit) => {
         'OrganizationInvitation',
         'OrganizationMembership',
         'OrganizationMembershipPublicUserData',
+        'Permission',
         'PhoneNumber',
         'RedirectUrl',
         'SMSMessage',

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

@@ -18,6 +18,7 @@ exports[`/server public exports should not include a breaking change 1`] = `
   "OrganizationInvitation",
   "OrganizationMembership",
   "OrganizationMembershipPublicUserData",
+  "Permission",
   "PhoneNumber",
   "RedirectUrl",
   "SMSMessage",

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

@@ -20,6 +20,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
   "OrganizationInvitation",
   "OrganizationMembership",
   "OrganizationMembershipPublicUserData",
+  "Permission",
   "PhoneNumber",
   "RedirectUrl",
   "SMSMessage",
@@ -52,6 +53,7 @@ exports[`module exports should not change unless explicitly set 1`] = `
   "invitations",
   "loadInterstitialFromLocal",
   "makeAuthObjectSerializable",
+  "organizationPermissions",
   "organizations",
   "phoneNumbers",
   "prunePrivateMetadata",

packages/sdk-node/src/index.ts

@@ -26,6 +26,7 @@ const {
   emails,
   invitations,
   organizations,
+  organizationPermissions,
   clients,
   allowlistIdentifiers,
   domains,
@@ -39,6 +40,7 @@ export {
   emails,
   invitations,
   organizations,
+  organizationPermissions,
   phoneNumbers,
   sessions,
   users,