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

# Public API

> `plugs/api/public.ts` - Public endpoints (no authentication required).

## Overview

Public API module containing endpoints that do not require authentication. These are typically used for login, logout, menu retrieval, and dictionary lookups.

## Endpoints

| Key | URL | Description |
|-----|-----|-------------|
| `dict` | `public/dict` | Dictionary data |
| `info` | `public/info` | User info (current) |
| `login` | `public/login` | Authentication |
| `logout` | `public/logout` | End session |
| `menu` | `public/menu` | Navigation menu |
| `actions` | `public/actions/{content}` | Actions for content |

## Exports

| Function | HTTP | Description |
|----------|------|-------------|
| `getByCodes` | GET | Get dictionary entries by codes |
| `getInfo` | GET | Get current user info |
| `login` | POST | Authenticate user |
| `logout` | PUT | End user session |
| `getMenus` | GET | Get navigation menus |
| `getActions` | GET | Get permitted actions for content |

---

## Functions

### getByCodes

```typescript
export const getByCodes = (codes) => {
  return new Promise((resolve, reject) => {
    get(urls.dict, codes).then(
      (rsp: any) => {
        if (rsp) {
          resolve(rsp);
        } else {
          resolve(false);
        }
      },
      (err) => {
        resolve(false);
      }
    );
  });
};
```

- **URL**: `public/dict`
- **Parameters**: `codes` - Array of dictionary codes
- **noMsg**: defaults to falsy
- **noLoading**: defaults to falsy
- **Returns**: Dictionary data or `false` on error

---

### getInfo

```typescript
export const getInfo = () => {
  return new Promise((resolve, reject) => {
    get(urls.info, null, true, true).then(
      (rsp: any) => {
        if (rsp) {
          resolve(rsp);
        } else {
          resolve(false);
        }
      },
      (err) => {
        resolve(false);
      }
    );
  });
};
```

- **URL**: `public/info`
- **noMsg**: `true` - Suppress messages
- **noLoading**: `true` - No loading indicator
- **Returns**: User info object or `false`

---

### login

```typescript
export const login = (user) => {
  return new Promise((resolve, reject) => {
    post(urls.login, user).then(
      (rsp: any) => {
        resolve(rsp);
      },
      (err) => {
        resolve(false);
      }
    );
  });
};
```

- **URL**: `public/login`
- **HTTP**: POST
- **Parameters**: `user` - Credentials object (e.g., `{ username, password }`)
- **Returns**: Response or `false` on error

---

### logout

```typescript
export const logout = () => {
  return new Promise((resolve, reject) => {
    put(urls.logout).then(
      (rsp: any) => {
        resolve(rsp);
      },
      (err) => {
        resolve(false);
      }
    );
  });
};
```

- **URL**: `public/logout`
- **HTTP**: PUT (unusual - typically DELETE or POST)
- **Returns**: Response or `false` on error

---

### getMenus

```typescript
export const getMenus = () => {
  return new Promise((resolve, reject) => {
    get(urls.menu, null, true, true).then(
      (rsp: any) => {
        if (rsp) {
          resolve(rsp);
        } else {
          resolve([]);
        }
      },
      (err) => {
        resolve([]);
      }
    );
  });
};
```

- **URL**: `public/menu`
- **noMsg**: `true`
- **noLoading**: `true`
- **Returns**: Menu array or `[]` on error (different from others that return `false`)

---

### getActions

```typescript
export const getActions = (content) => {
  return new Promise((resolve, reject) => {
    get(urls.actions + '/' + content, null, true, true).then(
      (rsp: any) => {
        if (rsp) {
          resolve(rsp);
        } else {
          resolve([]);
        }
      },
      (err) => {
        resolve([]);
      }
    );
  });
};
```

- **URL**: `public/actions/{content}`
- **Path Parameter**: `content` - Content identifier
- **noMsg**: `true`
- **noLoading**: `true`
- **Returns**: Actions array or `[]` on error

---

## Usage Example

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

// Login
const user = await pub.login({ username: 'admin', password: 'secret' });

// Get current user info
const info = await pub.getInfo();

// Get menus
const menus = await pub.getMenus();

// Get actions for content
const actions = await pub.getActions('user');

// Get dictionary entries
const dict = await pub.getByCodes(['status', 'type']);

// Logout
await pub.logout();
```

---

## Anti-Patterns

1. **`logout` uses PUT** - Should typically be DELETE or POST, not PUT
2. **Inconsistent error returns** - `getMenus`/`getActions` return `[]`, others return `false`
3. **No `reject`** - All promises resolve, never reject
4. **All custom implementations** - None use base module functions despite similar patterns