noob-components/.trellis/spec/plugs-api/role.md

Role API

plugs/api/role.ts - Role management operations.

Overview

Role management API with standard CRUD plus role-to-permission mapping lookup.

Endpoint

• Root: role
• Public: public/roles

Exports

Function	HTTP	Description
list	GET	List roles with optional filter
add	POST	Create new role
set	PUT	Update existing role
del	DELETE	Delete role by roleCode
mapping	GET	Get all roles (public endpoint)

---

Functions

list

export const list = (example) => {
  return queryList(root, example);
};

• Uses: queryList from base
• URL: role
• Parameters: example - Filter criteria (optional)

---

mapping

export const mapping = () => {
  return queryList(publik);
};

• Uses: queryList from base
• URL: public/roles (public endpoint, no auth required)
• Purpose: Fetch all roles for dropdown/radio selections

---

add

export const add = (role) => {
  return save(root, role);
};

• Uses: save from base (POST)
• Parameters: role - Role object to create

---

set

export const set = (role) => {
  return update(root, role);
};

• Uses: update from base (PUT)
• Parameters: role - Role object to update

---

del

export const del = (role) => {
  return deleteById(root, role.roleCode);
};

• Uses: deleteById from base (DELETE)
• ID Field: role.roleCode (not numeric ID)
• Note: Role identity is roleCode string, not numeric ID

---

Usage Example

import { role } from 'plugs/api';

// List roles
const roles = await role.list();

// Get all roles for mapping (public, no auth)
const allRoles = await role.mapping();

// Add role
await role.add({ roleCode: 'ADMIN', roleName: 'Administrator' });

// Update role
await role.set({ roleCode: 'ADMIN', roleName: 'Super Admin' });

// Delete role
await role.del({ roleCode: 'ADMIN' });

---

Anti-Patterns

1. del uses roleCode - Role deletion uses roleCode string, different from other APIs that use numeric IDs
2. mapping is public - Uses separate public endpoint, inconsistent with other list operations