From afda763bcd86544f6705af6b04a4ca2d9cb4163b Mon Sep 17 00:00:00 2001
From: Dustin Healy <54083382+dustinhealy@users.noreply.github.com>
Date: Wed, 25 Mar 2026 10:51:09 -0700
Subject: [PATCH] feat: add description field to Role model

- Add description to IRole, CreateRoleRequest, UpdateRoleRequest types
- Add description field to Mongoose roleSchema (default: '')
- Wire description through createRoleHandler and updateRoleHandler
- Include description in listRoles select clause so it appears in list
---
 packages/api/src/admin/roles.ts           | 7 ++++++-
 packages/data-schemas/src/methods/role.ts | 2 +-
 packages/data-schemas/src/schema/role.ts  | 1 +
 packages/data-schemas/src/types/role.ts   | 3 +++
 4 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/packages/api/src/admin/roles.ts b/packages/api/src/admin/roles.ts
index 4c3cd632af..8dbcc409ef 100644
--- a/packages/api/src/admin/roles.ts
+++ b/packages/api/src/admin/roles.ts
@@ -79,8 +79,9 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps) {
 
   async function createRoleHandler(req: ServerRequest, res: Response) {
     try {
-      const { name, permissions } = req.body as {
+      const { name, description, permissions } = req.body as {
         name?: string;
+        description?: string;
         permissions?: IRole['permissions'];
       };
       if (!name || typeof name !== 'string' || !name.trim()) {
@@ -88,6 +89,7 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps) {
       }
       const role = await createRoleByName({
         name: name.trim(),
+        description: description ?? '',
         permissions: permissions || {},
       });
       return res.status(201).json({ role });
@@ -113,6 +115,9 @@ export function createAdminRolesHandlers(deps: AdminRolesDeps) {
       if (body.name !== undefined) {
         updates.name = body.name;
       }
+      if (body.description !== undefined) {
+        updates.description = body.description;
+      }
 
       const role = await updateRoleByName(name, updates);
       return res.status(200).json({ role });
diff --git a/packages/data-schemas/src/methods/role.ts b/packages/data-schemas/src/methods/role.ts
index 998170b550..2c006bbd98 100644
--- a/packages/data-schemas/src/methods/role.ts
+++ b/packages/data-schemas/src/methods/role.ts
@@ -49,7 +49,7 @@ export function createRoleMethods(mongoose: typeof import('mongoose'), deps: Rol
    */
   async function listRoles() {
     const Role = mongoose.models.Role;
-    return await Role.find({}).select('name permissions').lean();
+    return await Role.find({}).select('name description permissions').lean();
   }
 
   /**
diff --git a/packages/data-schemas/src/schema/role.ts b/packages/data-schemas/src/schema/role.ts
index 1c27478ef6..ac478c2a83 100644
--- a/packages/data-schemas/src/schema/role.ts
+++ b/packages/data-schemas/src/schema/role.ts
@@ -73,6 +73,7 @@ const rolePermissionsSchema = new Schema(
 
 const roleSchema: Schema<IRole> = new Schema({
   name: { type: String, required: true, index: true },
+  description: { type: String, default: '' },
   permissions: {
     type: rolePermissionsSchema,
   },
diff --git a/packages/data-schemas/src/types/role.ts b/packages/data-schemas/src/types/role.ts
index 60a579240c..bc85284c34 100644
--- a/packages/data-schemas/src/types/role.ts
+++ b/packages/data-schemas/src/types/role.ts
@@ -5,6 +5,7 @@ import { CursorPaginationParams } from '~/common';
 
 export interface IRole extends Document {
   name: string;
+  description?: string;
   permissions: {
     [PermissionTypes.BOOKMARKS]?: {
       [Permissions.USE]?: boolean;
@@ -74,11 +75,13 @@ export type RolePermissionsInput = DeepPartial<RolePermissions>;
 
 export interface CreateRoleRequest {
   name: string;
+  description?: string;
   permissions: RolePermissionsInput;
 }
 
 export interface UpdateRoleRequest {
   name?: string;
+  description?: string;
   permissions?: RolePermissionsInput;
 }