[Goto Home](/docs/index.html)

# 🔐 GET `/admin/events`

## Description

- Returns event list as per pagination for admin.
- Events are sorted by `createdAt` descending.
- Each event includes populated `user` with `name`, `username`, and `photo`.

## Request Query

- `limit` – optional, natural number, default `"20"`, number of items per page
- `page` – optional, natural number, default `"1"`, page number

## Response Body

```json
{
  "events": [
    {
      "_id": "68e7536e877ea11a33be92e2",
      "user": {
        "_id": "68906b08a3bf95fd187f7a22",
        "name": "John Doe",
        "username": "john.doe",
        "photo": "https://..."
      },
      "title": "Let's Plant Many Trees",
      "description": "Lets meet at this sunday...",
      "date": "2025-10-12",
      "time": "11:00 AM",
      "location": {
        "type": "Point",
        "coordinates": [-71.0948037, 42.360092]
      },
      "locationString": "77 Massachusetts Ave, Cambridge, MA 02139",
      "chat": "68e7536e877ea11a33be92e0",
      "community": "68e7536e877ea11a33be92e3",
      "communities": ["68e7536e877ea11a33be92e3"],
      "category": "Plants",
      "joiningCost": 10,
      "membersLimit": 50,
      "featured": false,
      "cover": "https://...",
      "url": "https://meet.google.com/...",
      "startedAt": "2025-10-12T05:30:00.000Z",
      "endedAt": "2025-10-12T10:30:00.000Z",
      "createdAt": "2025-10-09T06:17:19.192Z",
      "updatedAt": "2025-10-09T06:17:19.192Z"
    }
  ],
  "count": 1
}
```

---

# 🔐 POST `/admin/events`

## Description

- Admin creates an event on behalf of a user by providing the user's **username** or **user `_id`**.
- Same behavior as user `POST /events`: creates the event and its chat, optional cover upload, and notifies nearby users via socket (`event-created`).
- `date` and `time` must produce a future timestamp.
- Chat will never have `exams` and `lectures` in `tags` array
- The target user is set as the event creator and as the chat admin.

## Request Body (Form Data)

Same fields as `POST /events`, plus one required field:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| **user** | string | ✅ | Target user: either **username** or user **`_id`** (MongoDB ObjectId). |
| title | string | ✅ | 5–200 characters. |
| description | string | ✅ | 10–5000 characters. |
| date | string | ✅ | `YYYY-MM-DD`. |
| time | string | ✅ | `hh:mm AM/PM` (e.g. `11:45 PM`). |
| locationString | string | ✅ | 3–180 characters. |
| latitude | string/number | ✅ | -90 to 90. |
| longitude | string/number | ✅ | -180 to 180. |
| category | string | ✅ | 2–20 characters. |
| cover | file | ❌ | Image file (optional). |
| communities | string[] | ❌ | Array of community `_id` (ObjectIds). |
| joiningCost | number | ❌ | Optional cost to join the event. |
| membersLimit | number | ❌ | Optional max number of members (≥ 0). |
| **featured** | `true`/`false` | ❌ | Optional. Only admin can set; marks the event as featured. |

Example:

```ts
{
  user: 'john.doe',   // or user._id e.g. '68906b08a3bf95fd187f7a22'
  title: 'Weekend Hangout',
  description: 'Join us for relaxed evening of coffee, chats and networking',
  date: '2025-10-30',
  time: '11:45 PM',
  locationString: 'Central Park, Rock-port, UK',
  latitude: '12.455',
  url?: 'https://meet.google.com/wef-hgi-sdhf',
  longitude: '-34.566',
  category: 'Event',
  cover?: <Image>,
  communities?: ['68e7536e877ea11a33be92e3'],
  joiningCost?: 10,
  membersLimit?: 50,
  featured?: true
}
```

## Response Body

Same as `POST /events`: returns the created **event** and **chat** objects.

```json
{
  "event": {
    "user": "68906b08a3bf95fd187f7a22",
    "title": "Let's Plant Many Trees",
    "description": "Lets meet at this sunday, plant many trees and make our nature healthy",
    "date": "2025-10-12",
    "time": "11:00 AM",
    "location": {
      "type": "Point",
      "coordinates": [-71.0948037, 42.360092]
    },
    "locationString": "77 Massachusetts Ave, Cambridge, MA 02139, United States",
    "chat": "68e7536e877ea11a33be92e0",
    "category": "Plants",
    "featured": false,
    "url?": "https://meet.google.com/wef-hgi-sdhf",
    "startedAt": "2025-10-12T05:30:00.000Z",
    "endedAt": "2025-10-12T10:30:00.000Z",
    "_id": "68e7536e877ea11a33be92e2",
    "cover": "https://...",
    "createdAt": "2025-10-09T06:17:19.192Z",
    "updatedAt": "2025-10-09T06:17:19.192Z"
  },
  "chat": {
    "creator": "68906b08a3bf95fd187f7a22",
    "isGroup": true,
    "name": "Let's Plant Many Trees",
    "allowPublicPost": true,
    "tags": [],
    "participants": [
      {
        "user": "68906b08a3bf95fd187f7a22",
        "isAdmin": true,
        "_id": "68e7536e877ea11a33be92e1",
        "lastReadAt": "2025-10-09T06:17:18.000Z"
      }
    ],
    "_id": "68e7536e877ea11a33be92e0",
    "event": "68e7536e877ea11a33be92e2",
    "photo": "https://...",
    "createdAt": "2025-10-09T06:17:18.872Z",
    "updatedAt": "2025-10-09T06:17:18.872Z"
  }
}
```

## Error Responses

- **400** – Validation error (e.g. missing/invalid fields, invalid `time` format).
- **403** – `date` and `time` produce a past timestamp.
- **404** – No user found for the given `user` (username or `_id`).
- **500** – Server error or cover upload failure.

---

# 🔐 PATCH `/admin/events/:id`

## Description

- Admin updates an existing event by its `_id`.
- Behaves the same as user `PATCH /events/:id`, except:
  - There is **no requirement** for the admin to be a participant or chat admin.
  - Validation and update rules are otherwise identical.
- If a new cover is uploaded, the previous image is deleted from storage and both the event and its chat are updated.
- If `date` is provided, then `time` is also required (and vice versa).
- If `latitude` is provided, then `longitude` is also required (and vice versa).
- Passing empty string (`''`) to the `url` field removes the URL from the event.
- In the background, notifies nearby users via socket with event `event-updated` (using both old and new locations when the location changes).

## Request Params

- `id` – required, MongoDB ObjectId of the event to update.

## Request Body (Form Data)

Same shape as user `PATCH /events/:id`:

```ts
{
  title?: 'Weekend Hangout',   // 5-200 characters
  description?: 'Join us for relaxed evening of coffee, chats and networking',     // 10-5000 characters
  date?: '2025-10-30',  // YYYY-MM-DD
  time?: '11:45 PM',    // hh:mm AM/PM
  locationString?: 'Central Park, Rock-port, UK',
  latitude?: '12.455',
  longitude?: '-34.566',
  category?: 'Open for Anything',
  url?: '' | 'https://meet.google.com/wef-hgi-sdhf',
  cover?: <Image>,
  communities?: ObjectId('communities')[],  // array of community _id
  joiningCost?: number,  // can only be updated for paid events
  membersLimit?: number,   // ≥ 0
  featured?: boolean
}
```

## Response Body

```json
{
  "cover": "https://pub-569168ecc9d940c3892a9d7197875513.r2.dev/chats/68e74a9dc73d76d52600a9de/1759990606589-10445846994269603-tree.png",
  "message": "event updated successfully"
}
```

---

# 🔐 DELETE `/admin/events/:id`

## Description

- Deletes an event by its `_id`. This action is performed **by an admin**.
- Behaves the same as user `DELETE /events/:id`:
  - Deletes **only** the event document (event cover file is **not** deleted).
  - Detaches the event from its chat by unsetting `chat.event` on the linked chat document.
  - In the background, emits socket `event-deleted` to:
    - All participants of the event's chat, and
    - All nearby users based on the event's `location`.
- Requires a valid admin session (`auth.authorizeAdmin`).

## Request Params

- `id` – required, MongoDB ObjectId of the event to delete.

## Response Body

```json
{
  "message": "event deleted successfully"
}
```