# Online Notes Viewer API Documentation

## Overview
The Online Notes Viewer API provides endpoints for student authentication, content access, payment processing, and admin management for the Online Notes platform.

## Setup for Testing
Before using the API, ensure you have test data:
1. Create at least one course via admin panel or database seeder
2. Note the course_id for user registration
3. For admin endpoints, ensure you have admin user authentication

**Base URL:** `http://localhost/api`

**Authentication:** Bearer Token (Laravel Sanctum)

## Authentication

### Request OTP
Send OTP to user's phone number for authentication.

**Endpoint:** `POST /auth/request-otp`

**Headers:**
```
Content-Type: application/json
```

**Request Body:**
```json
{
  "mobile": "+1234567890"
}
```

**Response (200):**
```json
{
  "message": "OTP sent successfully",
  "otp_expires_at": "2025-11-30T10:00:00Z"
}
```

**Error Responses:**
- 422: Validation error
- 429: Rate limited

### Verify OTP
Verify the OTP and return authentication token.

**Endpoint:** `POST /auth/verify-otp`

**Headers:**
```
Content-Type: application/json
```

**Request Body:**
```json
{
  "mobile": "+1234567890",
  "otp": "123456"
}
```

**Response (200):**
```json
{
  "message": "Login successful",
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890"
  },
  "token": "bearer_token_here"
}
```

### Register User
Register a new user after OTP verification.

**Endpoint:** `POST /auth/register`

**Headers:**
```
Content-Type: application/json
```

**Request Body:**
```json
{
  "name": "John Doe",
  "mobile": "+1234567890",
  "university": "Test University",
  "course_id": 1
}
```

**Note:** Ensure that a course with the specified `course_id` exists in the database before registration. You can create a course via the admin panel or database seeder.

**Response (201):**
```json
{
  "message": "User registered successfully",
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "course_id": 1
  },
  "token": "bearer_token_here"
}
```

### Logout
Revoke the current authentication token.

**Endpoint:** `POST /auth/logout`

**Headers:**
```
Authorization: Bearer {token}
```

**Response (200):**
```json
{
  "message": "Logged out successfully"
}
```

## Student Profile Management

### Get My Profile
Get the current authenticated student's profile.

**Endpoint:** `GET /students/me`

**Headers:**
```
Authorization: Bearer {token}
```

**Response (200):**
```json
{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "course_id": 1,
  "is_blocked": false,
  "created_at": "2025-11-30T09:00:00Z"
}
```

### Update Profile
Update the current student's profile information.

**Endpoint:** `PUT /students/me`

**Headers:**
```
Authorization: Bearer {token}
Content-Type: application/json
```

**Request Body:**
```json
{
  "name": "Updated Name",
  "email": "updated@example.com"
}
```

**Response (200):**
```json
{
  "message": "Profile updated successfully",
  "user": {
    "id": 1,
    "name": "Updated Name",
    "email": "updated@example.com"
  }
}
```

### Block Student (Admin)
Block or unblock a student account.

**Endpoint:** `POST /students/{id}/block`

**Headers:**
```
Authorization: Bearer {token}
```

**Response (200):**
```json
{
  "message": "Student blocked successfully"
}
```

## Content Management

### Get Courses
Get list of all available courses.

**Endpoint:** `GET /courses`

**Headers:**
```
Authorization: Bearer {token}
```

**Response (200):**
```json
[
  {
    "id": 1,
    "name": "Computer Science",
    "description": "CS Course Description",
    "created_at": "2025-11-30T09:00:00Z"
  }
]
```

### Get Semesters for Course
Get semesters for a specific course.

**Endpoint:** `GET /courses/{id}/semesters`

**Headers:**
```
Authorization: Bearer {token}
```

**Parameters:**
- `id` (path): Course ID

**Response (200):**
```json
[
  {
    "id": 1,
    "course_id": 1,
    "name": "Semester 1",
    "price_inr": 1000,
    "created_at": "2025-11-30T09:00:00Z"
  }
]
```

### Get Subjects for Semester
Get subjects for a specific semester.

**Endpoint:** `GET /semesters/{id}/subjects`

**Headers:**
```
Authorization: Bearer {token}
```

**Parameters:**
- `id` (path): Semester ID

**Response (200):**
```json
[
  {
    "id": 1,
    "semester_id": 1,
    "name": "Mathematics",
    "description": "Math Subject",
    "created_at": "2025-11-30T09:00:00Z"
  }
]
```

### Get Notes for Subject
Get notes for a specific subject.

**Endpoint:** `GET /subjects/{subjectId}/notes`

**Headers:**
```
Authorization: Bearer {token}
```

**Parameters:**
- `subjectId` (path): Subject ID

**Response (200):**
```json
[
  {
    "id": 1,
    "subject_id": 1,
    "title": "Algebra Notes",
    "description": "Basic algebra concepts",
    "file_path": "notes/algebra.pdf",
    "is_sample": false,
    "created_at": "2025-11-30T09:00:00Z"
  }
]
```

### Preview Note
Get preview of a note (first few pages).

**Endpoint:** `GET /notes/{noteId}/preview`

**Headers:**
```
Authorization: Bearer {token}
```

**Parameters:**
- `noteId` (path): Note ID

**Response:** PDF file stream

### View Full Note
Get full note content (requires entitlement).

**Endpoint:** `GET /notes/{noteId}/view`

**Headers:**
```
Authorization: Bearer {token}
```

**Parameters:**
- `noteId` (path): Note ID

**Response:** PDF file stream

## Payments

### Create Payment Intent
Create a payment intent for purchasing semester access.

**Endpoint:** `POST /payments/create-intent`

**Headers:**
```
Authorization: Bearer {token}
Content-Type: application/json
```

**Request Body:**
```json
{
  "semester_id": 1,
  "payment_method": "razorpay"
}
```

**Response (200):**
```json
{
  "payment_intent": {
    "id": "pay_test_123",
    "amount": 100000, // in paisa
    "currency": "INR",
    "order_id": "order_test_123"
  },
  "razorpay_key": "rzp_test_key"
}
```

### Get User Payments
Get payment history for a user.

**Endpoint:** `GET /users/{userId}/payments`

**Headers:**
```
Authorization: Bearer {token}
```

**Parameters:**
- `userId` (path): User ID

**Response (200):**
```json
[
  {
    "id": 1,
    "user_id": 1,
    "semester_id": 1,
    "amount": 1000,
    "currency": "INR",
    "status": "completed",
    "payment_id": "pay_test_123",
    "created_at": "2025-11-30T09:00:00Z"
  }
]
```

## Entitlements

### Get User Entitlements
Get all entitlements for a user.

**Endpoint:** `GET /users/{userId}/entitlements`

**Headers:**
```
Authorization: Bearer {token}
```

**Parameters:**
- `userId` (path): User ID

**Response (200):**
```json
[
  {
    "id": 1,
    "user_id": 1,
    "semester_id": 1,
    "expires_at": "2025-12-30T09:00:00Z",
    "created_at": "2025-11-30T09:00:00Z"
  }
]
```

### Check Entitlement
Check if user has entitlement for a specific semester.

**Endpoint:** `GET /users/{userId}/entitlements/check/{semesterId}`

**Headers:**
```
Authorization: Bearer {token}
```

**Parameters:**
- `userId` (path): User ID
- `semesterId` (path): Semester ID

**Response (200):**
```json
{
  "has_entitlement": true,
  "expires_at": "2025-12-30T09:00:00Z"
}
```

## Notifications

### Get User Notifications
Get notifications for a user.

**Endpoint:** `GET /users/{userId}/notifications`

**Headers:**
```
Authorization: Bearer {token}
```

**Parameters:**
- `userId` (path): User ID

**Response (200):**
```json
[
  {
    "id": 1,
    "user_id": 1,
    "title": "New Update",
    "message": "App has been updated",
    "is_read": false,
    "created_at": "2025-11-30T09:00:00Z"
  }
]
```


#### Get All Subjects
**Endpoint:** `GET /admin/subjects`

#### Create Course
**Endpoint:** `POST /admin/courses`

**Request Body:**
```json
{
  "name": "Computer Science",
  "description": "CS Course"
}
```

#### Create Semester
**Endpoint:** `POST /admin/semesters`

**Request Body:**
```json
{
  "course_id": 1,
  "name": "Semester 1",
  "price_inr": 1000
}
```

#### Create Subject
**Endpoint:** `POST /admin/subjects`

**Request Body:**
```json
{
  "semester_id": 1,
  "name": "Mathematics",
  "description": "Math Subject"
}
```

#### Update Subject
**Endpoint:** `PUT /admin/subjects/{subjectId}`

#### Delete Subject
**Endpoint:** `DELETE /admin/subjects/{subjectId}`

#### Upload Note
**Endpoint:** `POST /admin/subjects/{subjectId}/notes`

**Content-Type:** `multipart/form-data`

**Form Data:**
- `file`: PDF file
- `title`: Note title
- `description`: Note description
- `is_sample`: boolean

#### Update Note
**Endpoint:** `PUT /admin/notes/{noteId}`

#### Delete Note
**Endpoint:** `DELETE /admin/notes/{noteId}`

### Notifications Management

#### Get Notifications
**Endpoint:** `GET /admin/notifications`

#### Create Notification
**Endpoint:** `POST /admin/notifications`

**Request Body:**
```json
{
  "title": "New Update",
  "message": "App updated",
  "target_audience": "all"
}
```

#### Send Notification
**Endpoint:** `POST /admin/notifications/{notificationId}/send`

### Analytics

#### Dashboard Analytics
**Endpoint:** `GET /admin/analytics/dashboard`

**Response:**
```json
{
  "total_users": 100,
  "total_payments": 50,
  "total_revenue": 50000,
  "recent_registrations": 10
}
```

#### Purchase Analytics
**Endpoint:** `GET /admin/analytics/purchases`

#### Registration Analytics
**Endpoint:** `GET /admin/analytics/registrations`

## Webhooks

### Payment Webhook
Handle payment gateway webhooks.

**Endpoint:** `POST /webhook/payment-gateway`

**Headers:**
```
Content-Type: application/json
X-Razorpay-Signature: {signature}
```

**Supported Events:**
- `payment.captured`
- `payment.failed`

## Error Codes

### Common HTTP Status Codes
- `200`: Success
- `201`: Created
- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Validation Error
- `429`: Too Many Requests
- `500`: Internal Server Error

### Custom Error Responses
```json
{
  "message": "Validation failed",
  "errors": {
    "phone": ["The phone field is required."]
  }
}
```

```json
{
  "message": "Entitlement required",
  "error": "You don't have access to this content"
}
```

## Rate Limiting
- OTP requests: 3 per minute
- API requests: 60 per minute
- Payment requests: 10 per minute

## Authentication Notes
- All protected endpoints require `Authorization: Bearer {token}` header
- Tokens are issued via OTP verification
- Tokens expire after 24 hours of inactivity
- Admin endpoints require admin user authentication

## File Upload Notes
- Only PDF files are accepted
- Maximum file size: 10MB
- Files are stored securely with access controls