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

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

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

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

• 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.

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

• 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": {
    "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": "..."
}

Method: POST
Path: /create

• CreateSchedulerRequest: JSON object with scheduler details.

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

• 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.

Method: GET
Path: /forGame/{gameId}

• gameId (Long): ID of the game.

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

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

Method: GET
Path: /{schedulerId}

• schedulerId (Long): ID of the scheduler.

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

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

Method: PUT
Path: /edit

• EditSchedulerRequest: Updated scheduler details.

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

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

Method: DELETE
Path: /delete/{schedulerId}

• schedulerId (Long): ID of the scheduler.

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

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

Method: PUT
Path: /setFinalDecision

• SetFinalDecisionRequest: Final decision timeslot.

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

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

Method: GET
Path: /suggestedSlots/{schedulerId}

• schedulerId (Long): Scheduler ID.

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

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

Method: POST
Path: /sendFinalDecisionMails/{schedulerId}

• schedulerId (Long): Scheduler ID.

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

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

Method: POST
Path: /submitAvailability

• SubmitAvailabilityRequest: Availability slot list.

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

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

Method: PUT
Path: /editAvailability

• SubmitAvailabilityRequest: Updated availability slot list.

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

• Same as submitAvailability.

Method: GET
Path: /availability/{schedulerId}

• schedulerId (Long): Scheduler ID.

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

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

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

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

• 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.