edupage-cli 0.1.0

data/lib/edupage/models/day.rb

@@ -0,0 +1,51 @@
+module Edupage
+  module Models
+    # One day of a student's timetable.
+    class Day < Model
+      attribute :timetable_number, "tt_num", cast: :integer
+      attribute :timetable_day, "tt_day", cast: :integer
+      attribute :timetable_week, "tt_week", cast: :integer
+      attribute :timetable_term, "tt_term", cast: :integer
+
+      attr_reader :date
+
+      def initialize(data, school: nil, date: nil)
+        super(data, school: school)
+        @date = date.is_a?(String) ? Date.parse(date) : date
+      end
+
+      # Real lessons only; Edupage pads the plan with empty period rows.
+      def lessons
+        @lessons ||= Relation.wrap(all_entries.select(&:lesson?))
+      end
+
+      # Including the structural rows, for anyone rendering a full grid.
+      def entries = Relation.wrap(all_entries)
+
+      def lesson_at(period) = lessons.find { |l| l.period_number.to_s == period.to_s }
+
+      # Days off still come back with a plan, just without lessons.
+      def teaching_day? = lessons.any?
+
+      def absences = Array(data["student_absents"])
+
+      def id = date&.iso8601
+      def name = id
+
+      # Compact one-line view of the day, used by the table renderers.
+      def lesson_summary = lessons.map { |l| l.subject&.short || "?" }.join(" ")
+
+      def to_s = "#{id} #{lessons.map(&:to_s).join(" ")}"
+
+      def to_h
+        super.merge(date: id, lessons: lessons.map(&:to_h)).compact
+      end
+
+      private
+
+      def all_entries
+        @all_entries ||= Array(data["plan"]).map { |entry| Lesson.new(entry, school: school, date: date) }
+      end
+    end
+  end
+end

data/lib/edupage/models/grade.rb

@@ -0,0 +1,100 @@
+module Edupage
+  module Models
+    # A single mark.
+    #
+    # Edupage splits a grade in two: the row in `vsetkyZnamky` holds the value and who
+    # it belongs to, while everything descriptive - what it was for, how much it counts,
+    # the class average - lives on the event it references. Both are merged here, with
+    # the event kept under #event.
+    class Grade < Model
+      # p_typ_udalosti on the event: "1" is a classic 1-5 mark, "3" is points.
+      TYPE_MARK = "1".freeze
+      TYPE_POINTS = "3".freeze
+
+      # Edupage stores weights as a percentage of a "normal" grade, where 20 means 1.0.
+      WEIGHT_UNIT = 20.0
+
+      attribute :id, "znamkaid"
+      attribute :value, "data"
+      # The sub-period the grade sits in: "P2" for ordinary marks, "V2" for the ones
+      # that make up the end-of-term report. #term is the half-year it rolls up into.
+      attribute :period, "mesiac"
+      attribute :state, "stav"
+      attribute :provider
+      attribute :event_id, "udalostid"
+      attribute :created_at, "datum", cast: :time
+      attribute :signed_at, "podpisane", cast: :time
+      attribute :signed_by_parent_at, "podpisane_rodic", cast: :time
+      attribute(:subject) { |d| school&.subject(d["predmetid"]) }
+      attribute(:student) { |d| school&.student(d["studentid"]) }
+      attribute(:teacher) { |d| school&.teacher(d["ucitelid"]) }
+
+      attr_reader :event, :year, :term
+
+      def initialize(data, school: nil, event: nil, year: nil, term: nil)
+        super(data, school: school)
+        @event = event || {}
+        @year = year
+        @term = term
+      end
+
+      # --- from the event -------------------------------------------------------------
+
+      def title = presence(event["p_meno"])
+      def short = presence(event["p_skratka"])
+      def type = event["p_typ_udalosti"]
+      def due_on = Model.parse_date(event["p_termin"])
+      def class_average = event["priemer"]&.to_f
+      def school_class = school&.school_class(event["TriedaID"])
+
+      def weight
+        raw = event["p_vaha"]
+        raw.nil? || raw.to_s.empty? ? 1.0 : raw.to_f / WEIGHT_UNIT
+      end
+
+      # --- derived --------------------------------------------------------------------
+
+      def mark? = type == TYPE_MARK
+      def points? = type == TYPE_POINTS
+
+      def points = points? ? Float(value, exception: false) : nil
+
+      def max_points
+        return nil unless points?
+
+        Float(event["p_vaha_body"], exception: false)
+      end
+
+      def percentage
+        return nil unless points && max_points&.positive?
+
+        (points / max_points * 100).round(2)
+      end
+
+      def signed? = !signed_at.nil?
+      def signed_by_parent? = !signed_by_parent_at.nil?
+
+      def name = title || value
+
+      def match_strings = [id, value, title, short, subject&.short, subject&.name].compact.map(&:to_s)
+
+      def to_s
+        parts = [created_at&.strftime("%Y-%m-%d"), subject&.short, value]
+        parts << "(#{title})" if title
+        parts.compact.join(" ")
+      end
+
+      def to_h
+        super.merge(
+          title: title, weight: weight, type: type, points: points, max_points: max_points,
+          percentage: percentage, class_average: class_average,
+          year: year&.id, term: term&.id, signed_by_parent: signed_by_parent?
+        ).compact
+      end
+
+      private
+
+      def presence(value) = value.nil? || value.to_s.empty? ? nil : value.to_s
+    end
+  end
+end

data/lib/edupage/models/lesson.rb

@@ -0,0 +1,58 @@
+module Edupage
+  module Models
+    # One entry in a day's plan.
+    #
+    # Edupage mixes real lessons with structural rows (empty periods, breaks); #lesson?
+    # separates them. Each entry carries both a flat form (subjectid, teacherids, ...)
+    # and a nested presentation form under "header"/"infos"; the flat form is used here
+    # and the nested one is left in #data for anything not modelled.
+    class Lesson < Model
+      attribute :type
+      attribute :period_number, "period"
+      attribute :start_time, "starttime"
+      attribute :end_time, "endtime"
+      attribute :lesson_id, "lid"
+      attribute(:groups) { |d| Array(d["groupnames"]).reject { |g| g.to_s.empty? } }
+      attribute(:subject) { |d| school&.subject(d["subjectid"]) }
+      attribute(:period) { |d| school&.period(d["period"]) }
+      attribute(:teachers) { |d| Array(d["teacherids"]).filter_map { |id| school&.teacher(id) } }
+      attribute(:classrooms) { |d| Array(d["classroomids"]).filter_map { |id| school&.classroom(id) } }
+      attribute(:classes) { |d| Array(d["classids"]).filter_map { |id| school&.school_class(id) } }
+
+      attr_reader :date
+
+      def initialize(data, school: nil, date: nil)
+        super(data, school: school)
+        @date = date
+      end
+
+      def lesson? = type == "lesson"
+
+      def teacher = teachers.first
+      def classroom = classrooms.first
+
+      # "Učivo: ..." - what was actually taught, when the teacher filled it in.
+      def curriculum
+        info_text("wd")&.sub(/\A[^:]*:\s*/, "")
+      end
+
+      def id = [date, period_number, data["subjectid"]].compact.join(":")
+
+      def name = subject&.name
+      def short = subject&.short
+
+      def to_s
+        return "#{period_number}. -" unless lesson?
+
+        "#{period_number}. #{subject&.short || "?"}#{groups.empty? ? "" : " (#{groups.join(", ")})"}"
+      end
+
+      private
+
+      def info_text(type)
+        Array(data["infos"]).find { |info| info["type"] == type }
+                            &.dig("texts", 0, "text")
+      end
+    end
+  end
+end

data/lib/edupage/models/parent.rb

@@ -0,0 +1,8 @@
+module Edupage
+  module Models
+    # A guardian. dbi lists every pupil's parents, not only the account's own.
+    class Parent < Person
+      USER_STRING_PREFIX = "Rodic".freeze
+    end
+  end
+end

data/lib/edupage/models/period.rb

@@ -0,0 +1,13 @@
+module Edupage
+  module Models
+    # One slot in the daily bell schedule ("2nd period, 08:45-09:30").
+    class Period < Model
+      attribute :name
+      attribute :short
+      attribute :start_time, "starttime"
+      attribute :end_time, "endtime"
+
+      def to_s = "#{name}. #{start_time}-#{end_time}"
+    end
+  end
+end

data/lib/edupage/models/person.rb

@@ -0,0 +1,25 @@
+module Edupage
+  module Models
+    # Shared shape of everyone Edupage knows about: students, teachers and parents all
+    # carry the same name/gender/validity fields under the same keys.
+    class Person < Model
+      attribute :first_name, "firstname"
+      attribute :last_name, "lastname"
+      attribute :gender
+      attribute :valid_from, "datefrom", cast: :date
+      attribute :valid_to, "dateto", cast: :date
+      attribute :inactive, "isOut", cast: :boolean
+
+      alias inactive? inactive
+
+      def full_name = [first_name, last_name].compact.join(" ").strip
+      alias name full_name
+
+      # Edupage addresses people by a typed string such as "Student113506" or
+      # "Ucitel37135"; it appears all over the timeline payloads.
+      def user_string = "#{self.class::USER_STRING_PREFIX}#{id}"
+
+      def match_strings = (super + [full_name, user_string]).uniq
+    end
+  end
+end

data/lib/edupage/models/school_class.rb

@@ -0,0 +1,16 @@
+module Edupage
+  module Models
+    # A class group such as "2.A". Named SchoolClass because `Class` is taken.
+    class SchoolClass < Model
+      attribute :name
+      attribute :short
+      attribute :grade, "grade", cast: :integer
+      attribute(:teacher) { |d| school&.teacher(d["teacherid"]) }
+      attribute(:classroom) { |d| school&.classroom(d["classroomid"]) }
+
+      def students
+        Relation.new(-> { school.students.select { |s| s.school_class == self } })
+      end
+    end
+  end
+end

data/lib/edupage/models/student.rb

@@ -0,0 +1,45 @@
+module Edupage
+  module Models
+    # A pupil. For a parent account these are the account's own children, which is the
+    # entry point to everything year- and child-scoped.
+    class Student < Person
+      USER_STRING_PREFIX = "Student".freeze
+
+      attribute :number_in_class, "numberinclass", cast: :integer
+      attribute :number, "number", cast: :integer
+      attribute(:school_class) { |d| school&.school_class(d["classid"]) }
+      attribute(:parents) do |d|
+        %w[parent1id parent2id parent3id].filter_map { |key| school&.parent(d[key]) }
+      end
+
+      def class_name = school_class&.name
+
+      # --- year-scoped navigation -------------------------------------------------
+      # Grades and terms only exist within a school year, and Edupage keeps the
+      # selected year in the session, so they hang off a Year rather than the student.
+
+      def years = school.years_for(self)
+
+      def year(id)
+        years.find { |y| y.id == id.to_s } or
+          raise NotFoundError, "#{full_name} has no school year #{id}"
+      end
+
+      def current_year = years.find(&:current?) || years.first
+
+      # Convenience delegations: the common case is "this year".
+      def grades(...) = current_year.grades(...)
+      def terms(...) = current_year.terms(...)
+
+      # --- child-scoped, year-agnostic --------------------------------------------
+
+      def timetable(range = nil) = school.timetable_for(self, range)
+      def lessons(date = nil) = school.lessons_for(self, date)
+      def timeline = school.timeline_for(self)
+      def assignments = school.assignments_for(self)
+      def homeworks = assignments.where(type: Assignment::HOMEWORK_TYPES)
+
+      def to_s = "#{full_name}#{class_name ? " (#{class_name})" : ""}"
+    end
+  end
+end

data/lib/edupage/models/subject.rb

@@ -0,0 +1,9 @@
+module Edupage
+  module Models
+    # A taught subject, e.g. "Slovenský jazyk a literatúra" (SJL).
+    class Subject < Model
+      attribute :name
+      attribute :short
+    end
+  end
+end

data/lib/edupage/models/teacher.rb

@@ -0,0 +1,25 @@
+module Edupage
+  module Models
+    # A teacher. `short` is the code that appears in timetable cells.
+    class Teacher < Person
+      USER_STRING_PREFIX = "Ucitel".freeze
+
+      attribute :short
+      attribute :name_prefix, "nameprefix"
+      attribute :name_suffix, "namesuffix"
+      attribute :hidden_in_classbook, "cb_hidden", cast: :boolean
+      attribute(:classroom) { |d| school&.classroom(d["classroomid"]) }
+
+      alias hidden_in_classbook? hidden_in_classbook
+
+      # "Mgr. Mária Kováčová, PhD."
+      def full_name_with_titles
+        leading = [name_prefix.to_s.strip, full_name].reject(&:empty?).join(" ")
+        suffix = name_suffix.to_s.strip
+        suffix.empty? ? leading : "#{leading}, #{suffix}"
+      end
+
+      def match_strings = (super + [short]).compact.reject(&:empty?).uniq
+    end
+  end
+end

data/lib/edupage/models/term.rb

@@ -0,0 +1,36 @@
+module Edupage
+  module Models
+    # Half of a school year ("1. polrok"), as reported by yearterms.
+    #
+    # `grade_count` comes straight from Edupage and is the cheapest way to tell whether
+    # a term is worth fetching at all.
+    class Term < Model
+      attribute :id, "term"
+      attribute :name, "termName"
+      attribute :year_id, "yearid"
+      attribute :year_name, "yearName"
+      attribute :starts_on, "dateFrom", cast: :date
+      attribute :ends_on, "dateTo", cast: :date
+      attribute :grade_count, "numGrades", cast: :integer
+
+      attr_reader :year
+
+      def initialize(data, school: nil, year: nil)
+        super(data, school: school)
+        @year = year
+      end
+
+      def short = id
+
+      def grades = Relation.new(-> { year.grades_for(self) })
+
+      def current?
+        return false unless starts_on && ends_on
+
+        (starts_on..ends_on).cover?(Date.today)
+      end
+
+      def to_s = "#{year_name} #{name} (#{grade_count} grades)"
+    end
+  end
+end

data/lib/edupage/models/timeline_item.rb

@@ -0,0 +1,87 @@
+module Edupage
+  module Models
+    # One entry in the school feed.
+    #
+    # Edupage packs a second JSON document into the `data` field as a string; its shape
+    # depends on the item type. #payload decodes it lazily.
+    class TimelineItem < Model
+      # The types worth naming; there are many more and they pass through as-is.
+      TYPES = {
+        "sprava" => :message,
+        "nastenka" => :noticeboard,
+        "homework" => :homework,
+        "znamka" => :grade,
+        "student_absent" => :absence,
+        "ospravedlnenka" => :absence_note,
+        "substitution" => :substitution,
+        "timetable" => :timetable,
+        "stravamenu" => :canteen_menu,
+        "payments" => :payments,
+        "signin" => :signin,
+        "event" => :event,
+        "ucivo" => :curriculum,
+        "h_testvysledok" => :test_result,
+        "testpridelenie" => :test_assignment
+      }.freeze
+
+      attribute :id, "timelineid"
+      attribute :raw_type, "typ"
+      attribute :text
+      attribute :recipient_user_string, "user"
+      attribute :recipient_name, "user_meno"
+      attribute :owner_user_string, "vlastnik"
+      attribute :owner_name, "vlastnik_meno"
+      attribute :created_at, "cas_pridania", cast: :time
+      attribute :occurred_at, "cas_udalosti", cast: :time
+      attribute :reply_to_id, "reakcia_na"
+      attribute :reply_count, "pocet_reakcii", cast: :integer
+      attribute :removed, "removed", cast: :boolean
+      attribute :other_id, "ineid"
+
+      alias removed? removed
+
+      attr_reader :student
+
+      def initialize(data, school: nil, student: nil)
+        super(data, school: school)
+        @student = student
+      end
+
+      # A friendly symbol where one exists, otherwise the raw Edupage string.
+      def type = TYPES.fetch(raw_type) { raw_type }
+
+      def reply? = !reply_to_id.nil? && !reply_to_id.to_s.empty?
+
+      # The embedded JSON document, or an empty hash.
+      def payload
+        @payload ||= begin
+          raw = data["data"]
+          parsed = raw.is_a?(String) ? (JSON.parse(raw) rescue nil) : raw
+          parsed.is_a?(Hash) ? parsed : {}
+        end
+      end
+
+      def owner
+        @owner ||= school&.resolve_user_string(owner_user_string)
+      end
+
+      def recipient
+        @recipient ||= school&.resolve_user_string(recipient_user_string)
+      end
+
+      def title = payload["nazov"].to_s.empty? ? nil : payload["nazov"]
+
+      def name = title || text
+      def match_strings = [id, title, text, raw_type].compact.map(&:to_s).reject(&:empty?)
+
+      def to_s
+        label = [title, text].compact.map { |s| s.to_s.gsub(/\s+/, " ") }.reject(&:empty?).first
+        "#{created_at&.strftime("%Y-%m-%d %H:%M")} [#{type}] #{label}"
+      end
+
+      def to_h
+        super.merge(type: type, title: title, payload_keys: payload.keys).compact
+      end
+    end
+  end
+end

data/lib/edupage/parsers/base.rb

@@ -0,0 +1,150 @@
+require "json"
+require "strscan"
+
+module Edupage
+  module Parsers
+    # Every Edupage page ships its data as an argument to a JavaScript call:
+    #
+    #   $j(document).ready(function() { ... .userhome({"dbi":{...}}); });
+    #
+    # The upstream JS library pulls these out with `fn\(([\s\S]*?)\);` which stops at
+    # the first `);` - including one inside a string value, which does occur in message
+    # bodies and homework titles. This scans for balanced brackets instead, so the
+    # payload is extracted correctly regardless of its contents.
+    module Base
+      module_function
+
+      # Returns the parsed JSON argument of the first call to +function+, or nil.
+      #
+      # +arg+ selects which argument to take. Most calls put the payload first, but
+      # /gcall answers with `classbook.fill("Student113506", {...})`.
+      def extract_blob(html, function, arg: 0)
+        raw = extract_raw(html, function, arg: arg)
+        return nil unless raw
+
+        JSON.parse(raw)
+      rescue JSON::ParserError => e
+        raise ParseError.new("#{function}(...) argument #{arg} is not valid JSON: #{e.message}", snippet: raw)
+      end
+
+      def extract_blob!(html, function, arg: 0)
+        extract_blob(html, function, arg: arg) or
+          raise ParseError.new("Could not find #{function}(...) in the response", snippet: html)
+      end
+
+      # The literal source text of the first bracket-balanced argument.
+      #
+      # Scanning happens on a binary view of the document. StringScanner#pos counts
+      # bytes while String#[] counts characters, and these pages are full of Slovak
+      # diacritics - mixing the two silently walks off the end of a string literal and
+      # starts counting brackets inside it.
+      def extract_raw(html, function, arg: 0)
+        bytes = html.b
+        needle = function.b
+        index = 0
+
+        while (found = bytes.index(needle, index))
+          index = found + needle.bytesize
+          open = skip_spaces(bytes, index)
+          next unless bytes[open] == "("
+
+          start = argument_start(bytes, open, arg)
+          next unless start && ["{", "["].include?(bytes[start])
+
+          finish = match_bracket(bytes, start)
+          return bytes[start..finish].force_encoding(Encoding::UTF_8) if finish
+        end
+
+        nil
+      end
+
+      # ASC settings are plain assignments rather than a call:
+      #   ASC.gsechash = "803e65e8";
+      #   ASC.gpid = 62780423;
+      def extract_assignments(html, namespace)
+        html.scan(/#{Regexp.escape(namespace)}\.([A-Za-z0-9_$]+)\s*=\s*([^\n;]*);/)
+            .each_with_object({}) do |(key, value), result|
+          value = value.strip
+          next if value.start_with?("function")
+
+          result[key] = (JSON.parse("[#{value}]").first rescue value)
+        end
+      end
+
+      def skip_spaces(text, index)
+        index += 1 while text[index] =~ /\s/
+        index
+      end
+
+      BRACKETS = { "{" => "}", "[" => "]" }.freeze
+
+      # Matches either a complete JSON string literal or a single structural bracket.
+      #
+      # Consuming whole string literals in one match is what makes this correct: values
+      # in these payloads routinely contain brackets, and the timeline embeds an entire
+      # JSON document as an escaped string, so brackets must only be counted outside
+      # string literals.
+      TOKEN = /"(?:[^"\\]|\\.)*"|[{}\[\]]/m.freeze
+
+      # As TOKEN, plus the punctuation that separates call arguments.
+      ARGUMENT_TOKEN = /"(?:[^"\\]|\\.)*"|[{}\[\](),]/m.freeze
+
+      # Byte index where argument +wanted+ of a call begins, given the position of the
+      # opening parenthesis. Commas inside strings, objects or nested calls do not
+      # count as separators.
+      def argument_start(text, open, wanted)
+        return skip_spaces(text, open + 1) if wanted.zero?
+
+        scanner = StringScanner.new(text)
+        scanner.pos = open + 1
+        depth = 0
+        seen = 0
+
+        while scanner.scan_until(ARGUMENT_TOKEN)
+          token = scanner.matched
+          next if token.start_with?('"')
+
+          case token
+          when "{", "[", "(" then depth += 1
+          when "}", "]" then depth -= 1
+          when ")"
+            return nil if depth.zero? # argument list ended before we got there
+
+            depth -= 1
+          when ","
+            next unless depth.zero?
+
+            seen += 1
+            return skip_spaces(text, scanner.pos) if seen == wanted
+          end
+        end
+
+        nil
+      end
+
+      # Byte index of the bracket closing the one at +start+, or nil when unbalanced.
+      # +text+ must be a binary string; see #extract_raw.
+      def match_bracket(text, start)
+        scanner = StringScanner.new(text)
+        scanner.pos = start + 1
+        stack = [BRACKETS[text[start]]]
+
+        while scanner.scan_until(TOKEN)
+          char = scanner.matched
+          next if char.start_with?('"') # a whole string literal, skipped wholesale
+
+          if BRACKETS.key?(char)
+            stack.push(BRACKETS[char])
+          else
+            return nil unless char == stack.last
+
+            stack.pop
+            return scanner.pos - 1 if stack.empty?
+          end
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/edupage/parsers/gcall.rb

@@ -0,0 +1,53 @@
+module Edupage
+  module Parsers
+    # Timetable for an arbitrary date range.
+    #
+    # /user/ only ever carries about four days. Anything wider goes through /gcall,
+    # Edupage's generic widget RPC, which answers with a blob of JavaScript rather than
+    # JSON - the payload sits in the second argument of a `classbook.fill(...)` call.
+    class Gcall
+      PATH = "/gcall".freeze
+      CLASSBOOK_PATH = "/dashboard/eb.php?barNoSkin=1".freeze
+      FILL = "classbook.fill".freeze
+
+      def initialize(school)
+        @school = school
+      end
+
+      # Returns { "2026-09-21" => {day payload}, ... } for the requested range.
+      def load(student:, from:, to:)
+        body = @school.session.with_cursor(child: student.id) do |session|
+          session.post(PATH, {
+            "gpid" => gpid(session),
+            "gsh" => gsec_hash,
+            "action" => "loadData",
+            "datefrom" => from.iso8601,
+            "dateto" => to.iso8601
+          }).body
+        end
+
+        payload = Base.extract_blob(body, FILL, arg: 1)
+        return {} unless payload
+
+        payload["dates"] || {}
+      end
+
+      private
+
+      def gsec_hash
+        @school.document.gsec_hash or
+          raise ParseError, "No gsecHash on the dashboard; /gcall cannot be called without it"
+      end
+
+      # The widget id is minted per page load and appears only in the class book page.
+      def gpid(session)
+        @gpid ||= begin
+          ids = session.get(CLASSBOOK_PATH).body.scan(/gpid="?(\d+)"?/).flatten.uniq
+          raise ParseError, "No gpid on the class book page" if ids.empty?
+
+          ids.last
+        end
+      end
+    end
+  end
+end