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

# Permission API

> `plugs/api/permission.ts` - Permission management operations.

## Overview

Permission management API with standard CRUD plus permission tree retrieval.

## Endpoint

- **Root**: `permission`
- **Public**: `public/permission`

## Exports

| Function | HTTP | Description |
|----------|------|-------------|
| `list` | GET | List permissions with optional filter |
| `add` | POST | Create new permission |
| `set` | PUT | Update existing permission |
| `del` | DELETE | Delete permission by id |
| `tree` | GET | Get permission tree (public) |

---

## Functions

### list

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

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

---

### tree

```typescript
export const tree = () => {
  return queryList(publik);
};
```

- **Uses**: `queryList` from base
- **URL**: `public/permission` (public endpoint, no auth required)
- **Purpose**: Fetch hierarchical permission tree structure

---

### add

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

- **Uses**: `save` from base (POST)
- **Parameters**: `permission` - Permission object to create

---

### set

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

- **Uses**: `update` from base (PUT)
- **Parameters**: `permission` - Permission object to update

---

### del

```typescript
export const del = (permission) => {
  return deleteById(root, permission.id);
};
```

- **Uses**: `deleteById` from base (DELETE)
- **ID Field**: `permission.id` (numeric ID)
- **Note**: Permission identity is `id` numeric field

---

## Usage Example

```typescript
import { permission } from 'plugs/api';

// List permissions
const perms = await permission.list();

// Get permission tree (public, no auth)
const tree = await permission.tree();

// Add permission
await permission.add({ name: 'users:read', description: 'Read users' });

// Update permission
await permission.set({ id: 1, name: 'users:read', description: 'View users' });

// Delete permission
await permission.del({ id: 1 });
```

---

## Pattern Notes

- Similar structure to `role.ts` with both `list` and `tree` functions
- `tree` uses public endpoint, `list` uses authenticated endpoint