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

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

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

---

add

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

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

---

set

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

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

---

del

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

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

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

---

reset

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

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