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

# User API

> `plugs/api/user.ts` - User CRUD operations.

## Overview

User management API with standard CRUD plus password reset functionality.

## Endpoint

- **Root**: `user`

## Exports

| Function | HTTP | Description |
|----------|------|-------------|
| `list` | GET | List users with optional filter |
| `add` | POST | Create new user |
| `set` | PUT | Update existing user |
| `del` | DELETE | Delete user by userId |
| `updatePwd` | PUT | Update user password |
| `reset` | PUT | Reset user password |

---

## Functions

### list

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

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

---

### add

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

- **Uses**: `save` from base (POST)
- **Parameters**: `user` - User object to create

---

### set

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

- **Uses**: `update` from base (PUT)
- **Parameters**: `user` - User object to update

---

### del

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

- **Uses**: `deleteById` from base (DELETE)
- **ID Field**: `user.userId`
- **Note**: Pass the full user object, extracts `userId`

---

### updatePwd

```typescript
export const updatePwd = (pwd) => {
  return update(pwdUrl, pwd);
};
```

- **URL**: `user/password` (separate endpoint)
- **Uses**: `update` from base (PUT)
- **Parameters**: `pwd` - Password change payload

---

### reset

```typescript
export const reset = (user) => {
  return update(root + '/' + user.userId, {});
};
```

- **URL**: `user/{userId}` with empty body
- **Uses**: `update` from base (PUT)
- **Purpose**: Admin password reset

---

## Usage Example

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

// List users
const users = await user.list({ status: 1 });

// Add user
await user.add({ username: 'john', email: 'john@example.com' });

// Update user
await user.set({ userId: 123, username: 'johnny' });

// Delete user
await user.del({ userId: 123 });

// Change password
await user.updatePwd({ oldPwd: '...', newPwd: '...' });

// Reset user password (admin)
await user.reset({ userId: 123 });
```

---

## Anti-Patterns

1. **`del` requires full object** - Must pass `{ userId: ... }` not just the ID
2. **`reset` uses empty object** - Unclear why empty `{}` is sent as PUT body