Expand godoc

.cspell/custom-dictionary.txt

@@ -1,7 +1,8 @@
 # Custom Dictionary Words
-skola
 goskola
 pubtypes
+skola
+xscope
+zadachin
 zervo
 zervó
-zadachin

cmd/goskola24api/main.go

@@ -28,6 +28,8 @@ func main() {
 		}
 	}
 
+	terms, _ := api.GetTerms()
+
 	rooms, err := api.GetRooms(schools[4], true)
 	if err != nil {
 		fmt.Println(err.Error())
@@ -56,4 +58,11 @@ func main() {
 	}
 
 	fmt.Println(key)
+
+	schedule, err := api.GetWeekSchedule(2024, 50, schools[4], terms.ActiveTerms[0], classes[0])
+	if err != nil {
+		fmt.Println(err.Error())
+	}
+
+	fmt.Println(schedule)
 }

goskola24api.go

@@ -33,26 +33,37 @@ type Skola24API struct {
 	Host string
 }
 
+// Get all available terms (aka semesters) from the active host/domain
 func (api Skola24API) GetTerms() (_result pubtypes.Terms, _error error) {
 	return requests.GetTerms(api.Host)
 }
 
+// Get all available schools from the active host/domain
 func (api Skola24API) GetSchools() (_result []pubtypes.School, _error error) {
 	return requests.GetSchools(api.Host)
 }
 
+// Get all available rooms from a school
 func (api Skola24API) GetRooms(school pubtypes.School, checkAvailability bool) (_result []pubtypes.Room, _error error) {
 	return requests.GetRooms(school, checkAvailability)
 }
 
+// Get all available teachers from a school
 func (api Skola24API) GetTeachers(school pubtypes.School, checkAvailability bool) (_result []pubtypes.Teacher, _error error) {
 	return requests.GetTeachers(school, checkAvailability)
 }
 
+// Get all available students from a school (EXPERIMENTAL)
 func (api Skola24API) GetStudents(school pubtypes.School, checkAvailability bool) (_result any, _error error) {
 	return requests.GetStudents(school, checkAvailability)
 }
 
+// Get all available classes from a school
 func (api Skola24API) GetClasses(school pubtypes.School, checkAvailability bool) (_result []pubtypes.Class, _error error) {
 	return requests.GetClasses(school, checkAvailability)
 }
+
+// Get a week schedule for the provided date, school, term and class
+func (api Skola24API) GetWeekSchedule(year int, week int, school pubtypes.School, term pubtypes.SchoolTerm, class pubtypes.Class) (_result any, _error error) {
+	return requests.GetSchedule(year, week, 0, school, term, class)
+}

internal/requests/get_schedule.go

@@ -0,0 +1,89 @@
+/*
+GoSkola24API
+Copyright (C) 2024, Zervó Zadachin
+
+DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License version 3
+as published by the Free Software Foundation.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License version 3 for more details.
+
+This program incorporates external libraries for certain functionalities.
+These libraries are covered by their respective licenses, and their usage
+agreements are as outlined in their respective documentation or source
+code.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+package requests
+
+import (
+	"errors"
+	"fmt"
+
+	"git.zervo.org/zervo/goskola24api/internal/types"
+	"git.zervo.org/zervo/goskola24api/internal/utility"
+
+	pubtypes "git.zervo.org/zervo/goskola24api/types"
+)
+
+func GetSchedule(year int, week int, day int, school pubtypes.School, term pubtypes.SchoolTerm, class pubtypes.Class) (_result any, _error error) {
+	// Verify week number
+	if week > 52 || week < 1 {
+		return nil, errors.New("week number out of range (1-53): " + fmt.Sprint(week))
+	}
+
+	// Verify year
+	if year > 9999 || year < 2000 {
+		return nil, errors.New("year number out of range (2000-9999): " + fmt.Sprint(year))
+	}
+
+	// Verify day
+	if day > 7 || day < 0 {
+		return nil, errors.New("day number out of range (0-7): " + fmt.Sprint(day))
+	}
+
+	// Get render key
+	renderKey, err := utility.GetRendererKey()
+	if err != nil {
+		return nil, errors.New("failed to get render key: " + err.Error())
+	}
+
+	// Construct request
+	request := types.RequestSchedule{
+		RenderKey:            renderKey,
+		Host:                 school.HostName,
+		UnitGuid:             school.SchoolId,
+		StartDate:            nil,
+		EndDate:              nil,
+		ScheduleDay:          day,
+		BlackAndWhite:        false,
+		Width:                1000,
+		Height:               1000,
+		SelectionType:        0,
+		Selection:            class.ClassId,
+		ShowHeader:           false,
+		PeriodText:           "",
+		Week:                 week,
+		Year:                 year,
+		SchoolYear:           term.TermId,
+		PersonalTimetable:    false,
+		PrivateFreeTextMode:  nil,
+		PrivateSelectionMode: false,
+		CustomerKey:          "",
+	}
+
+	response, err := utility.Request(request, "render/timetable")
+	if err != nil {
+		return nil, errors.New("could not get schedule data: " + err.Error())
+	}
+
+	return response, nil
+}

internal/types/req_schedule.go

@@ -0,0 +1,48 @@
+/*
+GoSkola24API
+Copyright (C) 2024, Zervó Zadachin
+
+DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License version 3
+as published by the Free Software Foundation.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License version 3 for more details.
+
+This program incorporates external libraries for certain functionalities.
+These libraries are covered by their respective licenses, and their usage
+agreements are as outlined in their respective documentation or source
+code.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+package types
+
+type RequestSchedule struct {
+	RenderKey            string  `json:"renderKey"`
+	Host                 string  `json:"host"`
+	UnitGuid             string  `json:"unitGuid"`
+	StartDate            *string `json:"startDate"`
+	EndDate              *string `json:"endDate"`
+	ScheduleDay          int     `json:"scheduleDay"`
+	BlackAndWhite        bool    `json:"blackAndWhite"`
+	Width                int     `json:"width"`
+	Height               int     `json:"height"`
+	SelectionType        int     `json:"selectionType"`
+	Selection            string  `json:"selection"`
+	ShowHeader           bool    `json:"showHeader"`
+	PeriodText           any     `json:"periodText"`
+	Week                 int     `json:"week"`
+	Year                 int     `json:"year"`
+	SchoolYear           string  `json:"schoolYear"`
+	PersonalTimetable    bool    `json:"personalTimetable"`
+	PrivateFreeTextMode  *string `json:"privateFreeTextMode"`
+	PrivateSelectionMode bool    `json:"privateSelectionMode"`
+	CustomerKey          string  `json:"customerKey"`
+}

internal/types/response.go

@@ -25,10 +25,19 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 package types
 
 type BaseResponse struct {
-	Error              interface{}   `json:"error"`
-	Data               interface{}   `json:"data"`
-	Exception          interface{}   `json:"exception"`
-	Validation         []interface{} `json:"validation"`
-	SessionExpires     interface{}   `json:"sessionExpires"`
-	NeedSessionRefresh bool          `json:"needSessionRefresh"`
+	Error              interface{}    `json:"error"`
+	Data               interface{}    `json:"data"`
+	Exception          *ResponseError `json:"exception"`
+	Validation         []interface{}  `json:"validation"`
+	SessionExpires     interface{}    `json:"sessionExpires"`
+	NeedSessionRefresh bool           `json:"needSessionRefresh"`
+}
+
+type ResponseError struct {
+	Code      int     `json:"code"`
+	Context   string  `json:"context"`
+	ErrorId   int     `json:"errorId"`
+	ErrorTime string  `json:"errorTime"`
+	Message   *string `json:"message"`
+	Source    any     `json:"source"`
 }

internal/utility/request.go

@@ -71,6 +71,16 @@ func Request(data any, endpoint string) (_response interface{}, _error error) {
 	var responseData types.BaseResponse
 	json.Unmarshal(bodyBytes, &responseData)
 
+	// Check for reported exceptions
+	if responseData.Exception != nil {
+		return nil, errors.New("server replied with an exception")
+	}
+
+	// Check for reported errors
+	if responseData.Error != nil {
+		return nil, errors.New("server replied with an error")
+	}
+
 	// Return as raw bytes (let consumer do type assertion)
 	return responseData.Data, nil
 }

types/classes.go

@@ -24,17 +24,18 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 package types
 
+// Holds data about a class, which is usually a group of people studying a subject together
 type Class struct {
-	Name                            string `json:"name"`
-	ClassId                         string `json:"classId"`
-	AbsenceMessageNotDeliveredCount int    `json:"absenceMessageNotDeliveredCount"`
-	IsResponsible                   bool   `json:"isResponsible"`
-	IsClass                         bool   `json:"isClass"`
-	IsAdmin                         bool   `json:"isAdmin"`
-	IsPrincipal                     bool   `json:"isPrincipal"`
-	IsMentor                        bool   `json:"isMentor"`
-	IsPreschoolGroup                bool   `json:"isPreschoolGroup"`
-	Teachers                        any    `json:"teachers"` // TODO: MAKE TYPED
-	SubstituteTeacherId             string `json:"substituteTeacherId"`
-	TeacherChangeStudents           int    `json:"teacherChangeStudents"`
+	Name                            string `json:"name"`                            // Friendly-name of the class
+	ClassId                         string `json:"classId"`                         // UUID identifying the class
+	AbsenceMessageNotDeliveredCount int    `json:"absenceMessageNotDeliveredCount"` // Purpose unknown
+	IsResponsible                   bool   `json:"isResponsible"`                   // Purpose unknown
+	IsClass                         bool   `json:"isClass"`                         // Purpose unknown
+	IsAdmin                         bool   `json:"isAdmin"`                         // Purpose unknown
+	IsPrincipal                     bool   `json:"isPrincipal"`                     // Purpose unknown
+	IsMentor                        bool   `json:"isMentor"`                        // Purpose unknown
+	IsPreschoolGroup                bool   `json:"isPreschoolGroup"`                // Purpose unknown
+	Teachers                        any    `json:"teachers"`                        // Teachers for the class. TODO: MAKE TYPED
+	SubstituteTeacherId             string `json:"substituteTeacherId"`             // Teacher ID of the substitute teacher, if any
+	TeacherChangeStudents           int    `json:"teacherChangeStudents"`           // Purpose unknown
 }

types/rooms.go

@@ -24,8 +24,9 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 package types
 
+// Holds data about a room; a physical location within a school
 type Room struct {
-	Name     string `json:"name"`
-	RoomId   string `json:"roomId"`
-	External bool   `json:"external"`
+	Name     string `json:"name"`     // Name describing the room
+	RoomId   string `json:"roomId"`   // UUID identifying the room
+	External bool   `json:"external"` // Whether or not the room is external (purpose unknown)
 }

types/schedules.go

@@ -0,0 +1,36 @@
+/*
+GoSkola24API
+Copyright (C) 2024, Zervó Zadachin
+
+DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License version 3
+as published by the Free Software Foundation.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License version 3 for more details.
+
+This program incorporates external libraries for certain functionalities.
+These libraries are covered by their respective licenses, and their usage
+agreements are as outlined in their respective documentation or source
+code.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+package types
+
+import "time"
+
+// Holds data about a lesson, usually occurring once a week
+type Lesson struct {
+	LessonId  string    `json:"lessonId"`  // UUID identifying the lesson
+	DayOfWeek int       `json:"dayOfWeek"` // Day of the week where lesson occurs (monday=1)
+	Start     time.Time `json:"start"`     // Time when the lesson starts
+	End       time.Time `json:"end"`       // Time when the lesson ends
+	Texts     []string  `json:"texts"`     // Extra texts that may be displayed on a timetable
+}

types/schools.go

@@ -24,21 +24,23 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 package types
 
+// Holds data about a school
 type School struct {
-	Name                string           `json:"name"`
-	SchoolId            string           `json:"schoolId"`
-	HostName            string           `json:"hostName"`
-	AllowCalendarExport bool             `json:"allowCalendarExport"`
-	AvailableData       DataAvailability `json:"availableData"`
+	Name                string           `json:"name"`                // Friendly-name of the school
+	SchoolId            string           `json:"schoolId"`            // UUID identifying the school
+	HostName            string           `json:"hostName"`            // The hostname (domain) that the school belongs to
+	AllowCalendarExport bool             `json:"allowCalendarExport"` // Whether traditional calendar export is allowed, does not affect this module
+	AvailableData       DataAvailability `json:"availableData"`       // The types of data that the school provides
 }
 
+// Defines data availability, showing what type of data can be retrieved from an entity
 type DataAvailability struct {
-	HasClasses   bool `json:"hasClasses"`
-	HasCourses   bool `json:"hasCourses"`
-	HasGroups    bool `json:"hasGroups"`
-	HasResources bool `json:"hasResources"`
-	HasRooms     bool `json:"hasRooms"`
-	HasStudents  bool `json:"hasStudents"`
-	HasSubjects  bool `json:"hasSubjects"`
-	HasTeachers  bool `json:"hasTeachers"`
+	HasClasses   bool `json:"hasClasses"`   // Whether the school provides class data
+	HasCourses   bool `json:"hasCourses"`   // Whether the school provides course data
+	HasGroups    bool `json:"hasGroups"`    // Whether the school provides group data
+	HasResources bool `json:"hasResources"` // Whether the school provides resource data
+	HasRooms     bool `json:"hasRooms"`     // Whether the school provides room data
+	HasStudents  bool `json:"hasStudents"`  // Whether the school provides student data
+	HasSubjects  bool `json:"hasSubjects"`  // Whether the school provides subject data
+	HasTeachers  bool `json:"hasTeachers"`  // Whether the school provides teacher data
 }

types/teachers.go

@@ -24,14 +24,15 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 package types
 
+// Holds data about a teacher
 type Teacher struct {
-	FirstName  string `json:"firstName"`
-	LastName   string `json:"lastName"`
-	FullName   string `json:"fullName"`
-	FriendlyId string `json:"friendlyId"`
-	TeacherId  string `json:"teacherId"`
-	IsActive   bool   `json:"isActive"`
-	Integrity  bool   `json:"integrity"`
-	Reported   bool   `json:"reported"`
-	ReadOnly   bool   `json:"readOnly"`
+	FirstName  string `json:"firstName"`  // Teacher's first name
+	LastName   string `json:"lastName"`   // Teacher's last name
+	FullName   string `json:"fullName"`   // Teacher's full name, usually including their initials
+	FriendlyId string `json:"friendlyId"` // Friendly-ID of the teacher, usually their initials
+	TeacherId  string `json:"teacherId"`  // UUID identifying the teacher
+	IsActive   bool   `json:"isActive"`   // Purpose unknown
+	Integrity  bool   `json:"integrity"`  // Purpose unknown
+	Reported   bool   `json:"reported"`   // Purpose unknown
+	ReadOnly   bool   `json:"readOnly"`   // Purpose unknown
 }

types/terms.go

@@ -24,14 +24,16 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 package types
 
+// Holds data about a school term, aka semester
 type SchoolTerm struct {
-	Start  string `json:"start"`
-	TermId string `json:"termId"`
-	Name   string `json:"name"`
-	End    string `json:"end"`
+	Start  string `json:"start"`  // Start-date of the term
+	TermId string `json:"termId"` // UUID identifying the term
+	Name   string `json:"name"`   // Friendly-name of the term
+	End    string `json:"end"`    // End-date of the term
 }
 
+// Holds a list of active school terms
 type Terms struct {
-	ActiveTerms            []SchoolTerm `json:"activeSchoolYears"`
-	UseSchoolYearsFeatures bool         `json:"useSchoolYearsFeatures"`
+	ActiveTerms            []SchoolTerm `json:"activeSchoolYears"`      // List of active terms
+	UseSchoolYearsFeatures bool         `json:"useSchoolYearsFeatures"` // Purpose unknown
 }