# Data Transfer Objects (DTO)

## Overview
These definitions represent the strict contract between the Frontend (React) and Backend (Next.js API). They mirror the TypeScript interfaces found in `types.ts`.

## Core Entities

### 1. User DTO
**Type:** `UserDTO`
Used in authentication responses and author details.

| Field | Type | Description |
| :--- | :--- | :--- |
| `id` | `string` (UUID) | Unique identifier |
| `username` | `string` | Display name |
| `avatarUrl` | `string` | URL to profile image |
| `role` | `'USER' \| 'ADMIN' \| 'CREATOR'` | Permission level |
| `status` | `'ACTIVE' \| 'BANNED'` | Account standing |

### 2. Material DTO
**Type:** `MaterialDTO`
The main resource object.

| Field | Type | Description |
| :--- | :--- | :--- |
| `id` | `string` (UUID) | Unique identifier |
| `title` | `string` | Resource title |
| `description` | `string` | Short summary |
| `type` | `'CODE' \| 'ASSET_ZIP' \| 'VIDEO'` | Content category |
| `contentUrl` | `string?` | S3/CDN Link (Video/Zip) |
| `codeSnippet` | `string?` | Raw code string (Code only) |
| `language` | `string?` | e.g. 'typescript', 'python' |
| `author` | `UserDTO` | Nested author object |
| `stats` | `Object` | `{ views: number, downloads: number, favorites: number }` |

## Request Payloads

### Create Material Request
**POST** `/api/materials`

```typescript
interface CreateMaterialRequest {
  title: string;
  description: string;
  type: 'CODE' | 'ASSET_ZIP' | 'VIDEO';
  codeSnippet?: string; // Required if type is CODE
  contentUrl?: string;  // Required if type is VIDEO/ASSET
  tags: string[];
}
```

### Update User Profile Request
**PATCH** `/api/users/me`

```typescript
interface UpdateProfileRequest {
  username?: string;
  avatarUrl?: string;
  currentPassword?: string; // For security checks
  newPassword?: string;
}
```

## Response Wrappers

**Generic API Response**
All API endpoints return data wrapped in this structure for consistent error handling.

```typescript
interface ApiResponse<T> {
  success: boolean;
  data?: T;          // Present on success
  error?: {          // Present on failure
    code: string;    // e.g., 'AUTH_FAILED'
    message: string; // Human readable
  };
  timestamp: string; // ISO Date
}
```