Role Management

/**
 * Find realm roles with optional pagination
 * @param query - Optional pagination parameters
 * @returns Array of realm roles
 */
find(query?: RoleQuery): Promise<RoleRepresentation[]>;

/**
 * Create a new realm role
 * @param role - Role configuration
 * @returns Object with created role name
 */
create(role: RoleRepresentation): Promise<{ roleName: string }>;

/**
 * Find a specific realm role by name
 * @param params - Role name
 * @returns Role representation
 * @throws NetworkError if role not found
 */
findByName(params: { name: string }): Promise<RoleRepresentation>;

/**
 * Update an existing realm role
 * @param query - Role identifier
 * @param role - Updated role configuration
 */
update(query: { name: string }, role: RoleRepresentation): Promise<void>;

/**
 * Delete a realm role
 * @param params - Role identifier
 */
del(params: { name: string }): Promise<void>;

// List all realm roles
const realmRoles = await kcAdminClient.roles.find();
console.log("Realm roles:", realmRoles.map(r => r.name));

// Create new realm role
await kcAdminClient.roles.create({
  name: "application-admin",
  description: "Administrator role for the application",
  attributes: {
    department: ["IT"],
    level: ["admin"],
  },
});

// Find specific role
const adminRole = await kcAdminClient.roles.findByName({
  name: "application-admin",
});

// Update role
await kcAdminClient.roles.update(
  { name: "application-admin" },
  {
    description: "Updated: Administrator role for the application",
    attributes: {
      department: ["IT", "Security"],
      level: ["admin"],
    },
  }
);

// Delete role
await kcAdminClient.roles.del({ name: "temporary-role" });

/**
 * Get all composite roles for a realm role
 * @param params - Role identifier
 * @returns Array of composite roles (realm and client)
 */
getCompositeRoles(params: { name: string }): Promise<RoleRepresentation[]>;

/**
 * Get realm composite roles only
 * @param params - Role identifier
 * @returns Array of realm composite roles
 */
getCompositeRolesForRealm(params: { name: string }): Promise<RoleRepresentation[]>;

/**
 * Get client composite roles for a specific client
 * @param params - Role name and client identifier
 * @returns Array of client composite roles
 */
getCompositeRolesForClient(params: {
  name: string;
  clientId: string;
}): Promise<RoleRepresentation[]>;

/**
 * Add composite roles to a realm role
 * @param params - Role identifier and roles to add
 */
addCompositeRoles(params: {
  name: string;
  roles: RoleRepresentation[];
}): Promise<void>;

/**
 * Remove composite roles from a realm role
 * @param params - Role identifier and roles to remove
 */
delCompositeRoles(params: {
  name: string;
  roles: RoleRepresentation[];
}): Promise<void>;

// Create composite role
await kcAdminClient.roles.create({
  name: "super-admin",
  description: "Super administrator with all permissions",
  composite: true,
});

// Add realm roles to composite
const userRole = await kcAdminClient.roles.findByName({ name: "user" });
const adminRole = await kcAdminClient.roles.findByName({ name: "admin" });

await kcAdminClient.roles.addCompositeRoles({
  name: "super-admin",
  roles: [userRole, adminRole],
});

// Get all composite roles
const compositeRoles = await kcAdminClient.roles.getCompositeRoles({
  name: "super-admin",
});
console.log("Composite roles:", compositeRoles.map(r => r.name));

// Get only realm composite roles
const realmComposites = await kcAdminClient.roles.getCompositeRolesForRealm({
  name: "super-admin",
});

// Remove composite roles
await kcAdminClient.roles.delCompositeRoles({
  name: "super-admin",
  roles: [userRole],
});

/**
 * Find users who have a specific realm role
 * @param params - Role name and pagination options
 * @returns Array of users with the role
 */
findUsersWithRole(params: {
  name: string;
  first?: number;
  max?: number;
}): Promise<UserRepresentation[]>;

// Find all users with admin role
const adminUsers = await kcAdminClient.roles.findUsersWithRole({
  name: "admin",
});

console.log("Admin users:", adminUsers.map(u => u.username));

// Find users with pagination
const userPage = await kcAdminClient.roles.findUsersWithRole({
  name: "user",
  first: 0,
  max: 50,
});

/**
 * Note: Client roles are managed through the clients resource:
 * kcAdminClient.clients.createRole()
 * kcAdminClient.clients.listRoles()
 * kcAdminClient.clients.findRole()
 * kcAdminClient.clients.updateRole()
 * kcAdminClient.clients.delRole()
 */

// Client role operations are performed through clients resource
const clientId = "my-client-id";

// Create client role
await kcAdminClient.clients.createRole(
  { id: clientId },
  {
    name: "app-user",
    description: "Application user role",
    clientRole: true,
  }
);

// List client roles
const clientRoles = await kcAdminClient.clients.listRoles({
  id: clientId,
});

// Find specific client role
const appUserRole = await kcAdminClient.clients.findRole({
  id: clientId,
  roleName: "app-user",
});

// Update client role
await kcAdminClient.clients.updateRole(
  { id: clientId, roleName: "app-user" },
  {
    description: "Updated: Application user role",
  }
);

// Delete client role
await kcAdminClient.clients.delRole({
  id: clientId,
  roleName: "app-user",
});

/**
 * Role query parameters for pagination
 */
interface RoleQuery {
  /** Search term for role name */
  search?: string;
  /** Number of results to skip */
  first?: number;
  /** Maximum number of results to return */
  max?: number;
  /** Return brief representation */
  briefRepresentation?: boolean;
}

/**
 * Role representation with composite role support
 */
interface RoleRepresentation {
  /** Role unique identifier */
  id?: string;
  /** Role name */
  name?: string;
  /** Role description */
  description?: string;
  /** Whether role requires scope parameter */
  scopeParamRequired?: boolean;
  /** Whether role is composite */
  composite?: boolean;
  /** Composite role definitions */
  composites?: {
    /** Realm roles included in composite */
    realm?: string[];
    /** Client roles included in composite by client name */
    client?: Record<string, string[]>;
  };
  /** Whether this is a client role */
  clientRole?: boolean;
  /** Container ID (realm or client) */
  containerId?: string;
  /** Custom role attributes */
  attributes?: Record<string, string[]>;
}

// Pattern 1: Assign realm role to user
const user = await kcAdminClient.users.findOne({ id: userId });
const role = await kcAdminClient.roles.findByName({ name: "admin" });

await kcAdminClient.users.addRealmRoleMappings({
  id: userId,
  roles: [{ id: role.id, name: role.name }],
});

// Pattern 2: Assign client role to user
const clientRole = await kcAdminClient.clients.findRole({
  id: clientId,
  roleName: "app-admin",
});

await kcAdminClient.users.addClientRoleMappings({
  id: userId,
  clientUniqueId: clientId,
  roles: [{ id: clientRole.id, name: clientRole.name }],
});

// Pattern 3: Assign roles to group (inherited by members)
await kcAdminClient.groups.addRealmRoleMappings({
  id: groupId,
  roles: [{ id: role.id, name: role.name }],
});

// Pattern 4: Create role hierarchy with composites
await kcAdminClient.roles.create({
  name: "manager",
  composite: true,
});

const userRole = await kcAdminClient.roles.findByName({ name: "user" });
const reportRole = await kcAdminClient.roles.findByName({ name: "view-reports" });

await kcAdminClient.roles.addCompositeRoles({
  name: "manager",
  roles: [userRole, reportRole],
});