Skip to content

Add event model updates and status transition API #69

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lnqminh3003 merged 2 commits into from
Mar 4, 2026
Merged

Add event model updates and status transition API #69

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4f50e26
Add gameType, eventImg fields and status transition API to Event model
rxmox Mar 2, 2026
15b3630
Return 400 for Mongoose validation errors in createEvent
rxmox Mar 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 67 additions & 7 deletions shatter-backend/docs/API_REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
- [POST /api/events/createEvent](#post-apieventscreateevent)
- [GET /api/events/event/:joinCode](#get-apieventseventjoincode)
- [GET /api/events/:eventId](#get-apieventseventid)
- [PUT /api/events/:eventId/status](#put-apieventseventidstatus)
- [POST /api/events/:eventId/join/user](#post-apieventseventиdjoinuser)
- [POST /api/events/:eventId/join/guest](#post-apieventseventиdjoinguest)
- [GET /api/events/createdEvents/user/:userId](#get-apieventscreatedeventsuseriduserid)
Expand Down Expand Up @@ -64,6 +65,7 @@ Quick reference of all implemented endpoints. See detailed sections below for re
| POST | `/api/events/createEvent` | Protected | Create a new event |
| GET | `/api/events/event/:joinCode` | Public | Get event by join code |
| GET | `/api/events/:eventId` | Public | Get event by ID |
| PUT | `/api/events/:eventId/status` | Protected | Update event lifecycle status (host-only) |
| POST | `/api/events/:eventId/join/user` | Protected | Join event as authenticated user |
| POST | `/api/events/:eventId/join/guest` | Public | Join event as guest |
| GET | `/api/events/createdEvents/user/:userId` | Protected | Get events created by user |
Expand Down Expand Up @@ -416,7 +418,7 @@ Get all events a user has joined (populates event details).
"joinCode": "12345678",
"startDate": "2025-02-01T18:00:00.000Z",
"endDate": "2025-02-01T21:00:00.000Z",
"currentState": "active"
"currentState": "In Progress"
}
]
}
Expand Down Expand Up @@ -492,10 +494,12 @@ Create a new event.
|------------------|--------|----------|-------|
| `name` | string | Yes | |
| `description` | string | Yes | Required by schema |
| `gameType` | string | Yes | Must be `"Name Bingo"` |
| `startDate` | string | Yes | ISO 8601 date |
| `endDate` | string | Yes | Must be after `startDate` |
| `maxParticipant` | number | Yes | |
| `currentState` | string | Yes | Free-form string (no enum) |
| `currentState` | string | No | One of: `"Upcoming"`, `"In Progress"`, `"Completed"`. Defaults to `"Upcoming"` |
| `eventImg` | string | No | URL for event image |

**Success Response (201):**

Expand All @@ -506,12 +510,14 @@ Create a new event.
"_id": "665a...",
"name": "Tech Meetup",
"description": "Monthly networking event",
"gameType": "Name Bingo",
"joinCode": "48291037",
"startDate": "2025-02-01T18:00:00.000Z",
"endDate": "2025-02-01T21:00:00.000Z",
"maxParticipant": 50,
"participantIds": [],
"currentState": "pending",
"currentState": "Upcoming",
"eventImg": "https://example.com/event-image.jpg",
"createdBy": "664f...",
"createdAt": "2025-01-20T12:00:00.000Z",
"updatedAt": "2025-01-20T12:00:00.000Z"
Expand Down Expand Up @@ -555,7 +561,8 @@ Get event details by join code.
"participantIds": [
{ "_id": "666b...", "name": "John Doe", "userId": "664f..." }
],
"currentState": "active",
"currentState": "Upcoming",
"gameType": "Name Bingo",
"createdBy": "664f...",
...
}
Expand Down Expand Up @@ -610,6 +617,60 @@ Get event details by event ID.

---

### PUT `/api/events/:eventId/status`

Update an event's lifecycle status. Only the event host (creator) can change the status.

- **Auth:** Protected (host-only — `event.createdBy` must match authenticated user)

**URL Params:**

| Param | Type | Required |
|-----------|----------|----------|
| `eventId` | ObjectId | Yes |

**Request Body:**

| Field | Type | Required | Notes |
|----------|--------|----------|-------|
| `status` | string | Yes | Target status. One of: `"In Progress"`, `"Completed"` |

**Valid Transitions:**

| From | To |
|---------------|----------------|
| `Upcoming` | `In Progress` |
| `In Progress` | `Completed` |

**Success Response (200):**

```json
{
"success": true,
"event": {
"_id": "665a...",
"name": "Tech Meetup",
"currentState": "In Progress",
...
}
}
```

**Error Responses:**

| Status | Error |
|--------|-------|
| 400 | `"Status is required"` |
| 400 | `"Invalid status transition from <current> to <target>"` |
| 403 | `"Only the event host can update the event status"` |
| 404 | `"Event not found"` |

**Side Effects:**
- **Upcoming → In Progress:** Emits Pusher event `event-started` on channel `event-{eventId}` with payload `{ status: 'In Progress' }`
- **In Progress → Completed:** Emits Pusher event `event-ended` on channel `event-{eventId}` with payload `{ status: 'Completed' }`

---

### POST `/api/events/:eventId/join/user`

Join an event as a registered (authenticated) user.
Expand Down Expand Up @@ -1064,7 +1125,6 @@ These endpoints are **not yet implemented**. Do not depend on them.

| Method | Endpoint | Description |
|--------|----------|-------------|
| PUT | `/api/events/:eventId/status` | Update event lifecycle state (host-only) |
| POST | `/api/events/:eventId/leave` | Leave an event |
| DELETE | `/api/events/:eventId` | Cancel/delete an event |
| GET | `/api/events/:eventId/participants` | Search/list participants |
Expand Down Expand Up @@ -1110,10 +1170,10 @@ curl -X POST http://localhost:4000/api/events/createEvent \
-d '{
"name": "Tech Meetup",
"description": "Monthly networking event",
"gameType": "Name Bingo",
"startDate": "2025-02-01T18:00:00.000Z",
"endDate": "2025-02-01T21:00:00.000Z",
"maxParticipant": 50,
"currentState": "pending"
"maxParticipant": 50
}'
```

Expand Down
30 changes: 16 additions & 14 deletions shatter-backend/docs/DATABASE_SCHEMA.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,20 +102,22 @@

### Fields

| Field | Type | Required | Default | Notes |
|------------------|------------|----------|---------|-------|
| `_id` | ObjectId | Auto | Auto | |
| `name` | String | Yes | — | |
| `description` | String | Yes | — | |
| `joinCode` | String | Yes | — | Unique, auto-generated 8-digit number |
| `startDate` | Date | Yes | — | |
| `endDate` | Date | Yes | — | Must be after `startDate` |
| `maxParticipant` | Number | Yes | — | |
| `participantIds` | [ObjectId] | No | `[]` | Refs `Participant` |
| `currentState` | String | Yes | — | Free-form string (no enum validation) |
| `createdBy` | ObjectId | Yes | — | User who created the event (no ref set) |
| `createdAt` | Date | Auto | Auto | Mongoose timestamps |
| `updatedAt` | Date | Auto | Auto | Mongoose timestamps |
| Field | Type | Required | Default | Notes |
|------------------|---------------|----------|--------------|-------|
| `_id` | ObjectId | Auto | Auto | |
| `name` | String | Yes | — | |
| `description` | String | Yes | — | |
| `joinCode` | String | Yes | — | Unique, auto-generated 8-digit number |
| `gameType` | String (enum) | Yes | — | One of: `'Name Bingo'` |
| `eventImg` | String | No | — | URL for event image |
| `startDate` | Date | Yes | — | |
| `endDate` | Date | Yes | — | Must be after `startDate` |
| `maxParticipant` | Number | Yes | — | |
| `participantIds` | [ObjectId] | No | `[]` | Refs `Participant` |
| `currentState` | String (enum) | Yes | `'Upcoming'` | One of: `'Upcoming'`, `'In Progress'`, `'Completed'` |
| `createdBy` | ObjectId | Yes | — | User who created the event (no ref set) |
| `createdAt` | Date | Auto | Auto | Mongoose timestamps |
| `updatedAt` | Date | Auto | Auto | Mongoose timestamps |

### Indexes

Expand Down
Loading