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

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

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

---

### mapping

```typescript
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

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

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

---

### set

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

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

---

### del

```typescript
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

```typescript
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