noob-components/.trellis/spec/plugs-http/misc.md

# Misc HTTP Utilities

> Shared types and utilities for HTTP clients.

## File

`plugs/http/misc.ts`

---

## Overview

Contains shared type definitions and utility functions used across all HTTP client variants.

---

## PageResponse Type

```typescript
export interface PageResponse<T> {
  data: T[];
  page?: number;
  total: number;
}
```

### Type Properties

| Property | Type | Description |
|----------|------|-------------|
| `data` | `T[]` | Array of items for current page |
| `page` | `number?` | Current page number (optional) |
| `total` | `number` | Total count of all items |

### Usage Example

```typescript
import { PageResponse } from '@/plugs/http';

interface User {
  id: number;
  name: string;
}

const response: PageResponse<User> = {
  data: [{ id: 1, name: 'John' }],
  page: 1,
  total: 100
};
```

---

## pageEmpty Utility

```typescript
export const pageEmpty = <T>(): PageResponse<T> => ({
  data: [],
  total: 0,
});
```

### Purpose

Creates an empty paginated response with typed data array. Useful for:

- Initial state in components
- Default values in API calls
- Fallback when data fetch fails

### Usage Example

```typescript
import { pageEmpty } from '@/plugs/http';

// In a Vue component
const userList = ref<User>(pageEmpty());

// After API call fails
userList.value = pageEmpty();
```

---

## Type Relationships

```
plugs/http/
├── axios.ts    - Raw response handling
├── axios2.ts   - PageResponse via response.data
├── axios3.ts   - PageResponse via response.data (with filter)
└── misc.ts     - PageResponse<T> definition
```

---

## Common Response Patterns

### Success Response

```typescript
{
  success: true,
  data: [...],       // or PageResponse<T>
  message: "Operation successful"
}
```

### Error Response

```typescript
{
  success: false,
  message: "Error description",
  error: "Detailed error info"  // sometimes present
}
```

### Session Timeout

```typescript
{
  success: false,
  message: "session timeout"
}
```

### Permission Denied

```typescript
{
  success: false,
  message: "no permission"
}
// or
{
  success: false,
  message: "no permission for resource:xxx"
}
```

---

## Export from Index

Located at `plugs/http/index.ts`:

```typescript
export * as Axios from "./axios";
export * as Axios2 from "./axios2";
export * as Axios3 from "./axios3";
export * from "./misc";
```

### Import Patterns

```typescript
// Import specific types
import { PageResponse, pageEmpty } from '@/plugs/http';

// Import all axios variants
import { Axios, Axios2, Axios3 } from '@/plugs/http';

// Full access
import { Axios3, PageResponse } from '@/plugs/http';
```