SchedulerController

SchedulerController

This page contains documentation for the SchedulerController class, which handles RPG session schedulers.

Basic Information

Base Path: /api/v1/authorized/schedulers
Package: dev.goral.rpghandyhelper.scheduler.controller

Authentication

All requests to this controller require an XSRF token to be included in the headers.
Example:

headers: {
  "X-XSRF-TOKEN": "<csrfToken>"
}

---

Endpoint Summary

HTTP Method	Path	Description
POST	/create	Creates a new scheduler
GET	/forGame/{gameId}	Gets schedulers for a specific game
GET	/{schedulerId}	Gets a scheduler by ID
PUT	/edit	Edits an existing scheduler
DELETE	/delete/{schedulerId}	Deletes a scheduler
PUT	/setFinalDecision	Sets the final decision for a scheduler
GET	/suggestedSlots/{schedulerId}	Returns suggested time slots for the scheduler
POST	/sendFinalDecisionMails/{schedulerId}	Sends email confirmation with final decision
GET	/pendingSchedulers	Returns pending schedulers for user
GET	/nextSession/{gameId}	Returns nearest final decision for game
POST	/submitAvailability	Submits availability for a scheduler
PUT	/editAvailability	Edits previously submitted availability
GET	/availability/{schedulerId}	Gets current user's submitted availability
GET	/availability/{schedulerId}/all	Gets all user's submitted availability

---

Field Descriptions

Request Body Fields

• title (String): Title of the scheduler.
• deadline (DateTime): Deadline to submit availability.
• minimumSessionDurationMinutes (Integer): Minimum session length in minutes.
• gameId (Long): ID of the associated game.
• creatorId (Long): ID of the user creating the scheduler.
• dateRanges (Array): List of date ranges with start/end date and time.
• participantIds (Array[Long]): List of user IDs invited to submit availability.

Availability Slot Fields

• startDateTime (DateTime): Start of availability slot.
• endDateTime (DateTime): End of availability slot.
• availabilityType (Enum): One of YES, MAYBE, NO.

---

Response Fields

• message (String): Operation result.
• error (Integer): HTTP status code.
• timestamp (String): Time of response.
• scheduler (Object): Single scheduler response.
• schedulers (Array): List of scheduler responses.
• suggestedSlots (Array): Suggested time slot options.
• availability (Object): Availability of current user.

Scheduler Sample Object that is mentioned in responses

{
  "scheduler": {
    "id": 1,
    "title": "Spotkanie RPG: Początek Kampanii",
    "deadline": "2026-12-15T23:59:59",
    "minimumSessionDurationMinutes": 60,
    "gameId": 1,
    "creatorId": 1,
    "dateRanges": [
      {
        "startDate": "2025-12-20",
        "endDate": "2025-12-22"
      },
      {
        "startDate": "2025-12-27",
        "endDate": "2025-12-28"
      }
    ],
    "timeRanges": [
      {
        "startTime": "18:00:00",
        "endTime": "22:00:00"
      },
      {
        "startTime": "19:00:00",
        "endTime": "23:30:00"
      }
    ],
    "participants": [
      {
        "id": 1,
        "playerId": 1,
        "notifiedByEmail": true
      },
      {
        "id": 2,
        "playerId": 2,
        "notifiedByEmail": true
      }
    ],
    "finalDecision": null,
    "status": "AWAITING_AVAILABILITY",
    "missingAvailabilitiesCount": 2,
    "googleCalendarLink": null,
    "emailsSent": false
  },
  "message": "Utworzono harmonogram.",
  "error": 200,
  "timestamp": "..."
}

---

Endpoint Details

Create a New Scheduler

Method: POST
Path: /create

Request Body

• CreateSchedulerRequest: JSON object with scheduler details.

Response Example

{
  "message": "Utworzono harmonogram.",
  "error": 200,
  "timestamp": "...",
  "scheduler": { ... }
}

Possible Errors

• 400 Bad Request: Missing or invalid fields.
• 401 Unauthorized: User is not authenticated.
• 403 Forbidden: User is not the Game Master.
• 404 Not Found: Game or creator does not exist.

---

Get Schedulers for a Specific Game

Method: GET
Path: /forGame/{gameId}

Path Parameters

• gameId (Long): ID of the game.

Response Example

{
  "message": "Pobrano listę harmonogramów.",
  "error": 200,
  "timestamp": "...",
  "schedulers": [ ... ]
}

Possible Errors

• 403 Forbidden: User does not belong to the game.
• 404 Not Found: Game not found.

---

Get Scheduler by ID

Method: GET
Path: /{schedulerId}

Path Parameters

• schedulerId (Long): ID of the scheduler.

Response Example

{
  "message": "Pobrano harmonogram.",
  "error": 200,
  "timestamp": "...",
  "scheduler": { ... }
}

Possible Errors

• 403 Forbidden: User has no access to this scheduler.
• 404 Not Found: Scheduler not found.

---

Edit an Existing Scheduler

Method: PUT
Path: /edit

Request Body

• EditSchedulerRequest: Updated scheduler details.

Response Example

{
  "message": "Zaktualizowano scheduler.",
  "error": 200,
  "timestamp": "...",
  "scheduler": { ... }
}

Possible Errors

• 403 Forbidden: User is not the creator.
• 400 Bad Request: Invalid fields.
• 404 Not Found: Scheduler not found.

---

Delete a Scheduler

Method: DELETE
Path: /delete/{schedulerId}

Path Parameters

• schedulerId (Long): ID of the scheduler.

Response Example

{
  "message": "Scheduler został usunięty.",
  "error": 200,
  "timestamp": "..."
}

Possible Errors

• 403 Forbidden: Only the creator can delete.
• 404 Not Found: Scheduler not found.

---

Set Final Decision

Method: PUT
Path: /setFinalDecision

Request Body

• SetFinalDecisionRequest: Final decision timeslot.

Response Example

{
  "message": "Ustawiono ostateczny termin.",
  "error": 200,
  "timestamp": "...",
  "scheduler": { ... }
}

Possible Errors

• 400 Bad Request: Slot too short or invalid time.
• 403 Forbidden: Only the creator can finalize.
• 404 Not Found: Scheduler not found.

---

Suggest Time Slots

Method: GET
Path: /suggestedSlots/{schedulerId}

Path Parameters

• schedulerId (Long): Scheduler ID.

Response Example

{
  "message": "Pobrano proponowane przedziały.",
  "error": 200,
  "timestamp": "...",
  "suggestedSlots": [ ... ]
}

Possible Errors

• 403 Forbidden: No access to scheduler.
• 404 Not Found: Scheduler not found.

---

Send Final Decision Mails

Method: POST
Path: /sendFinalDecisionMails/{schedulerId}

Path Parameters

• schedulerId (Long): Scheduler ID.

Response Example

{
  "message": "Wysłano wiadomości e-mail z potwierdzeniem terminu.",
  "error": 200,
  "timestamp": "..."
}

Possible Errors

• 400 Bad Request: Already sent or no decision.
• 403 Forbidden: Only creator can send.
• 404 Not Found: Scheduler not found.

---

Submit Availability

Method: POST
Path: /submitAvailability

Request Body

• SubmitAvailabilityRequest: Availability slot list.

Response Example

{
  "message": "Dostępność została zapisana.",
  "error": 200,
  "timestamp": "..."
}

Possible Errors

• 400 Bad Request: Invalid slot ranges.
• 403 Forbidden: Not a participant.
• 404 Not Found: Scheduler not found.

---

Edit Availability

Method: PUT
Path: /editAvailability

Request Body

• SubmitAvailabilityRequest: Updated availability slot list.

Response Example

{
  "message": "Dostępność została zaktualizowana.",
  "error": 200,
  "timestamp": "..."
}

Possible Errors

• Same as submitAvailability.

---

Get Current User Availability

Method: GET
Path: /availability/{schedulerId}

Path Parameters

• schedulerId (Long): Scheduler ID.

Response Example

{
  "message": "Pobrano dostępność gracza.",
  "error": 200,
  "timestamp": "...",
  "availability": { ... }
}

---

Get All Player Availabilities

Method: GET
Path: /availability/{schedulerId}/all

Response Example

{
  "message": "Pobrano dostępność graczy.",
  "error": 200,
  "timestamp": "...",
  "availability": [ ... ]
}

Possible Errors

• 403 Forbidden: User has no access to scheduler.
• 404 Not Found: Scheduler not found.

---

Common Troubleshooting Tips

• Missing XSRF Token: Ensure the X-XSRF-TOKEN header is included in every request.
• Finalized Scheduler: You cannot edit a scheduler or submit availability once finalized.
• Access Issues: Only GameMasters can create/edit/delete schedulers.
• Validation Errors: Ensure date ranges, time ranges, and availability slots are valid.