# @math-platform/shared-types

TypeScript type definitions shared between frontend and backend applications.

## Purpose

Eliminates duplication and misalignment between frontend and backend type definitions.

## Structure

```
shared/types/
├── package.json          # Package configuration
├── tsconfig.json         # TypeScript configuration
└── src/
    ├── index.ts          # Main entry point - exports all types
    ├── auth.ts           # Authentication types
    ├── exercise.ts       # Exercise and attempt types
    ├── module.ts         # Module and topic types
    ├── progress.ts       # Progress tracking types
    ├── achievement.ts    # Achievement and badge types
    ├── ranking.ts        # Leaderboard types
    ├── api.ts            # Generic API types
    ├── error.ts          # Error types and classes
    └── utils.ts          # Utility types
```

## Installation

### Frontend

Types are accessed via path mapping in `tsconfig.json`:

```json
{
  "compilerOptions": {
    "paths": {
      "@math-platform/shared-types": ["../shared/types/src"],
      "@math-platform/shared-types/*": ["../shared/types/src/*"]
    }
  }
}
```

### Backend

Same path mapping in `tsconfig.json`:

```json
{
  "compilerOptions": {
    "paths": {
      "@math-platform/shared-types": ["../../shared/types/src"],
      "@math-platform/shared-types/*": ["../../shared/types/src/*"]
    }
  }
}
```

## Usage

### Import Types

```typescript
// Import specific types
import type { 
  User, 
  Exercise, 
  LoginRequest, 
  LoginResponse,
  SubmitAttemptRequest,
  SubmitAttemptResponse,
  ApiResponse 
} from '@math-platform/shared-types';

// Import from specific module
import type { LoginRequest, LoginResponse } from '@math-platform/shared-types/auth';
import type { Exercise, SubmitAttemptRequest } from '@math-platform/shared-types/exercise';
```

### Import Classes

```typescript
// Error classes are exported as values
import { 
  ApplicationError,
  ValidationError,
  NotFoundError 
} from '@math-platform/shared-types';
```

## Key Contracts

### 1. Submit Attempt

**Request:**
```typescript
interface SubmitAttemptRequest {
  answer: string;
  timeSpent: number;
  hintsUsed?: number;
  skipped?: boolean;
}
```

**Response:**
```typescript
interface SubmitAttemptResponse {
  isCorrect: boolean;
  points: number;
  message: string;
  correctAnswer?: string;
  solutionSteps?: SolutionStep[];
  newAchievements?: AchievementUnlock[];
}
```

### 2. Auth

**Login Request:**
```typescript
interface LoginRequest {
  email: string;
  password: string;
}
```

**Login Response:**
```typescript
interface LoginResponse {
  token: string;
  refreshToken?: string;
  expiresIn?: number;
  user: User;
}
```

### 3. API Response

```typescript
interface ApiResponse<T = unknown> {
  success: boolean;
  data?: T;
  error?: ApiError;
  meta?: ApiMeta;
}
```

## Migration Guide

### Before (Duplicated)

**Frontend:** `frontend/src/types/index.ts`
```typescript
export interface LoginData {
  email: string;
  password: string;
}
```

**Backend:** `backend/src/shared/types/index.ts`
```typescript
export interface LoginInput {
  email: string;
  password: string;
}
```

### After (Shared)

Both use:
```typescript
import type { LoginRequest } from '@math-platform/shared-types';
```

## Best Practices

1. **Always use `type` imports** for type-only imports to avoid circular dependencies
2. **Keep types serializable** - use `string` for dates, not `Date` objects
3. **Document breaking changes** in CHANGELOG.md
4. **Don't import from specific backend/frontend packages** - keep this package independent

## Building

```bash
cd shared/types
npm install
npm run build
```

## Type Checking

```bash
npm run type-check
```
