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

# Config API

> `plugs/api/config.ts` - System configuration management.

## Overview

System configuration API with list and update operations, plus single value retrieval.

## Endpoint

- **Root**: `config`

## Exports

| Function | HTTP | Description |
|----------|------|-------------|
| `list` | GET | List config entries with filter |
| `set` | PUT | Update existing config entry |
| `getValue` | GET | Get config value by key |

---

## Functions

### list

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

- **Uses**: `queryPage` from base
- **URL**: `config`
- **Parameters**: `example` - Filter criteria (optional)
- **Returns**: Paginated result

---

### set

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

- **Uses**: `update` from base (PUT)
- **Parameters**: `config` - Config object to update

---

### getValue

```typescript
export const getValue = (key) => {
  return new Promise((resolve, reject) => {
    get(root + '/' + key, null, true, true).then(
      (rsp: any) => {
        resolve(rsp);
      },
      (err) => {
        resolve(null);
      }
    );
  });
};
```

- **URL**: `config/{key}`
- **Parameters**: `key` - Configuration key
- **noMsg**: `true` - Suppress success message
- **noLoading**: `true` - Suppress loading indicator
- **Returns**: `null` on error (not `false` or `{}`)

---

## Usage Example

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

// List all configs
const configs = await config.list();

// List filtered configs
const dbConfigs = await config.list({ category: 'database' });

// Update config
await config.set({ key: 'app.name', value: 'My App', id: 1 });

// Get single config value
const appName = await config.getValue('app.name');
```

---

## Pattern Notes

- No `add` function - configs are typically only updated, not created
- `getValue` returns `null` on error (different from other APIs that return `false`)
- `getValue` uses custom implementation instead of `getById` from base

---

## Anti-Patterns

1. **Missing `add` function** - Inconsistent with other CRUD APIs
2. **Custom `getValue` instead of `getById`** - Could use base's `getById` with URL template