edupage-cli 0.1.0

data/lib/edupage/parsers/timeline.rb

@@ -0,0 +1,46 @@
+require "json"
+
+module Edupage
+  module Parsers
+    # The timeline is the school's activity feed: messages, homework, absences, canteen
+    # menus, sign-ups, substitutions.
+    #
+    # For a parent it is a single feed covering every child, not one feed per child, so
+    # nothing needs switching to read it - but each item has to be attributed. That is
+    # what childGroups is for: it lists every userstring that stands for a given child
+    # ("Student113506", "Trieda-2", "CustPlan8503", ...), and an item belongs to the
+    # child whose list contains its recipient.
+    class Timeline
+      PATH = "/timeline/?akcia=getData".freeze
+
+      attr_reader :items, :child_groups
+
+      def initialize(items, child_groups: {})
+        @items = Array(items)
+        @child_groups = child_groups
+      end
+
+      # /user/ already carries the recent feed, so the common case needs no extra fetch.
+      def self.from_userhome(document)
+        new(document.items, child_groups: document.child_groups)
+      end
+
+      def self.parse(json, child_groups: {})
+        payload = json.is_a?(String) ? JSON.parse(json) : json
+        new(payload["items"] || payload["timelineItems"] || [], child_groups: child_groups)
+      end
+
+      # Userstrings that stand for the given student.
+      def groups_for(student_id)
+        Array(child_groups[student_id.to_s]).to_set
+      end
+
+      def for_student(student_id)
+        groups = groups_for(student_id)
+        return items if groups.empty?
+
+        items.select { |item| groups.include?(item["user"].to_s) }
+      end
+    end
+  end
+end

data/lib/edupage/parsers/userhome.rb

@@ -0,0 +1,84 @@
+module Edupage
+  module Parsers
+    # Reads /user/, which is the workhorse page: one fetch carries the whole school
+    # directory (dbi), four days of timetable (dp), the timeline feed (items) and the
+    # per-child group membership needed to attribute those items.
+    #
+    # Three separate payloads live in that HTML and all three matter:
+    #   .userhome({...})   the data above
+    #   .edubar({...})     session state - selected year, current child
+    #   ASC.x = y;         school identity and the gsecHash needed by /gcall
+    class Userhome
+      def self.parse(html)
+        new(
+          Base.extract_blob!(html, ".userhome"),
+          edubar: Base.extract_blob(html, ".edubar") || {},
+          asc: Base.extract_assignments(html, "ASC")
+        )
+      end
+
+      attr_reader :data, :edubar, :asc
+
+      def initialize(data, edubar: {}, asc: {})
+        @data = data
+        @edubar = edubar
+        @asc = asc
+      end
+
+      # --- school directory ---------------------------------------------------------
+
+      def dbi = data["dbi"] || {}
+
+      # dbi collections are keyed by id, except periods which arrive as an array.
+      def collection(name) = normalize(dbi[name])
+
+      # --- timetable ----------------------------------------------------------------
+
+      def dates = data.dig("dp", "dates") || {}
+
+      # --- timeline -----------------------------------------------------------------
+
+      def items = Array(data["items"])
+
+      # Maps a child id to every userstring that stands for them ("Student113506",
+      # "Trieda-2", "CustPlan8503", ...). Timeline items are addressed to one of these,
+      # so this is how a shared parent feed is split per child.
+      def child_groups = data["childGroups"] || {}
+
+      def parent_student_ids = Array(data["parentStudentids"]).map(&:to_s)
+
+      # --- identity and session state -----------------------------------------------
+
+      def user_id = data["userid"] || edubar["loggedUser"]
+      def user_row = data["userrow"] || {}
+      def user_name = edubar["loggedUserName"] || [user_row["p_meno"], user_row["p_priezvisko"]].compact.join(" ")
+      def login = user_row["p_www_login"]
+      def email = user_row["p_mail"]
+
+      def school_name = asc["school_name"]
+      def origin = asc["edupage"] || edubar["edupage"]
+      def language = asc["lang"]
+      def gsec_hash = asc["gsechash"]
+
+      # The year the session is pointed at, which is not necessarily the current one.
+      def selected_year = edubar["selectedYear"]&.to_s
+
+      # The real current year, unaffected by the cursor.
+      def current_year = edubar["autoYear"]&.to_s || selected_year
+
+      def logged_child = edubar["loggedChild"]&.to_s
+
+      def teaching_days = Array(edubar["vyucovacieDni"])
+
+      private
+
+      def normalize(value)
+        case value
+        when Hash then value.values
+        when Array then value
+        else []
+        end
+      end
+    end
+  end
+end

data/lib/edupage/parsers/znamky.rb

@@ -0,0 +1,83 @@
+module Edupage
+  module Parsers
+    # Reads /znamky/, which carries a whole school year for the currently selected
+    # child: the grades themselves, the events they hang off, and the list of years and
+    # terms the child has data for.
+    #
+    # The page takes its year from the session cursor (see Session#set_year), so the
+    # caller pins the year and this just reads whatever came back.
+    class Znamky
+      PATH = "/znamky/?barNoSkin=1".freeze
+      VIEWER = "znamkyStudentViewer".freeze
+      SETTINGS = "initZnamkovanieSettings".freeze
+
+      # One request only ever returns one half-year, selected by `nadobdobie`. Asking
+      # for a year therefore means asking for each of its terms and merging.
+      def self.path_for(term: nil)
+        term ? "#{PATH}&nadobdobie=#{term}" : PATH
+      end
+
+      def self.parse(html)
+        new(Base.extract_blob!(html, VIEWER), settings: Base.extract_blob(html, SETTINGS) || {})
+      end
+
+      attr_reader :data, :settings
+
+      def initialize(data, settings: {})
+        @data = data
+        @settings = settings
+      end
+
+      def student_id = data["studentid"]&.to_s
+      def year_id = data["yearid"]&.to_s
+      def year_name = data["skRok"]
+
+      # The half-year this response covers.
+      def term_id = data["nadobdobie"]&.to_s
+
+      def grades = Array(data["vsetkyZnamky"])
+
+      # Grades carry an event id but none of the interesting metadata; the title,
+      # weight, class average and maximum points all live on the event.
+      # Shape: { provider => { event_id => event } }
+      def events
+        @events ||= (data["vsetkyUdalosti"] || {}).each_with_object({}) do |(provider, rows), result|
+          result[provider] = normalize(rows).to_h { |event| [event["UdalostID"].to_s, event] }
+        end
+      end
+
+      def event_for(grade)
+        events.dig(grade["provider"].to_s, grade["udalostid"].to_s)
+      end
+
+      # Every (year, term) pair the child has, each with how many grades are in it -
+      # the cheapest way to find where the data actually is.
+      def year_terms = Array(data["yearterms"])
+
+      # Period definitions for the year, keyed by id (P1, KL1, V1, P2, ...).
+      #
+      # A grade's `mesiac` is one of these sub-periods, not the half-year itself: the
+      # P2 response contains grades marked P2 and V2 ("vysvedčenie"). `nadobdobie`
+      # points a sub-period at the half-year it belongs to.
+      def periods = settings["obdobia"] || {}
+
+      # Half-year a sub-period rolls up into; a half-year maps to itself.
+      def parent_period(id)
+        periods.dig(id.to_s, "nadobdobie") || id.to_s
+      end
+
+      # Subjects this child is graded in, which is a subset of the school's subjects.
+      def subjects = normalize(data["predmety"])
+
+      private
+
+      def normalize(value)
+        case value
+        when Hash then value.values
+        when Array then value
+        else []
+        end
+      end
+    end
+  end
+end

data/lib/edupage/registry/resources.rb

@@ -0,0 +1,175 @@
+module Edupage
+  # Every resource this tool exposes, declared once.
+  #
+  # Adding a resource here gives it a CLI command, a REST route and an MCP tool with no
+  # further work; leaving one out of any surface is impossible by construction.
+  class Registry
+    # --- account ----------------------------------------------------------------------
+
+    resource :account do
+      scope :account
+      summary "The logged-in account"
+      table_fields :username, :name
+      resolve ->(account, _) { account }
+    end
+
+    resource :schools do
+      scope :account
+      summary "Schools this account can reach"
+      table_fields :origin, :name, :role
+      resolve ->(account, _) { account.schools }
+    end
+
+    # --- school directory -------------------------------------------------------------
+    #
+    # These all read one /user/ document, so asking for several in a row costs one fetch.
+
+    resource :students do
+      scope :school
+      summary "Students visible to the account (a parent sees their own children)"
+      param :name, desc: "Filter by name"
+      param :class, desc: "Filter by class, e.g. 2.A"
+      table_fields :full_name, :class_name, :number_in_class
+      resolve lambda { |school, p|
+        school.students(year: p[:year]).where(name: p[:name], school_class: p[:class])
+      }
+    end
+
+    resource :teachers do
+      scope :school
+      summary "Teachers"
+      param :name, desc: "Filter by name or short code"
+      table_fields :short, :full_name_with_titles
+      resolve ->(school, p) { school.teachers(year: p[:year]).where(name: p[:name]) }
+    end
+
+    resource :parents do
+      scope :school
+      summary "Parents"
+      param :name, desc: "Filter by name"
+      table_fields :full_name
+      resolve ->(school, p) { school.parents(year: p[:year]).where(name: p[:name]) }
+    end
+
+    resource :classes do
+      scope :school
+      summary "Classes"
+      param :name, desc: "Filter by name"
+      table_fields :name, :grade, :teacher
+      resolve ->(school, p) { school.classes(year: p[:year]).where(name: p[:name]) }
+    end
+
+    resource :classrooms do
+      scope :school
+      summary "Rooms"
+      param :name, desc: "Filter by name"
+      table_fields :short, :name
+      resolve ->(school, p) { school.classrooms(year: p[:year]).where(name: p[:name]) }
+    end
+
+    resource :subjects do
+      scope :school
+      summary "Subjects"
+      param :name, desc: "Filter by name or short code"
+      table_fields :short, :name
+      resolve ->(school, p) { school.subjects(year: p[:year]).where(name: p[:name]) }
+    end
+
+    resource :periods do
+      scope :school
+      summary "The bell schedule"
+      table_fields :name, :start_time, :end_time
+      resolve ->(school, p) { school.periods(year: p[:year]) }
+    end
+
+    # --- student ----------------------------------------------------------------------
+
+    resource :timetable do
+      scope :student
+      summary "Timetable days"
+      param :date, type: :date, desc: "A single day (defaults to today)"
+      param :from, type: :date, desc: "Start of a range"
+      param :to, type: :date, desc: "End of a range"
+      table_fields :date, :lesson_summary
+      resolve lambda { |student, p|
+        if p[:from] || p[:to]
+          from = p[:from] || Date.today
+          student.timetable(from..(p[:to] || from + 6))
+        else
+          Relation.wrap([student.timetable(p[:date])].compact)
+        end
+      }
+    end
+
+    resource :lessons do
+      scope :student
+      summary "Lessons on one day"
+      param :date, type: :date, desc: "Defaults to today"
+      param :subject, desc: "Filter by subject"
+      table_fields :period_number, :subject, :teachers, :classrooms, :start_time, :end_time
+      resolve ->(student, p) { student.lessons(p[:date]).where(subject: p[:subject]) }
+    end
+
+    resource :assignments do
+      scope :student
+      summary "Homework, tests, exams and projects"
+      param :type, desc: "Filter by type, e.g. hw or test"
+      param :subject, desc: "Filter by subject"
+      param :due, type: :date, desc: "Only items due on or after this date"
+      table_fields :due_on, :type, :subject, :title
+      resolve lambda { |student, p|
+        scope = student.assignments.where(type: p[:type], subject: p[:subject])
+        scope = scope.where(due_on: p[:due]..) if p[:due]
+        scope.order(:due_on)
+      }
+    end
+
+    resource :homeworks do
+      scope :student
+      summary "Homework only, including tasks set to one pupil rather than the class"
+      param :subject, desc: "Filter by subject"
+      param :due, type: :date, desc: "Only items due on or after this date"
+      table_fields :due_on, :subject, :title, :class_wide?
+      resolve lambda { |student, p|
+        scope = student.homeworks.where(subject: p[:subject])
+        scope = scope.where(due_on: p[:due]..) if p[:due]
+        scope.order(:due_on)
+      }
+    end
+
+    resource :timeline do
+      scope :student
+      summary "The school feed for this student"
+      param :type, desc: "Filter by item type, e.g. message or homework"
+      table_fields :created_at, :type, :name
+      resolve ->(student, p) { student.timeline.where(type: p[:type]).order(created_at: :desc) }
+    end
+
+    resource :years do
+      scope :student
+      summary "School years this student has data for"
+      table_fields :id, :name, :current?, :grade_count
+      resolve ->(student, _) { student.years }
+    end
+
+    # --- year -------------------------------------------------------------------------
+
+    resource :terms do
+      scope :year
+      summary "Terms of a school year, with how many grades each holds"
+      table_fields :id, :name, :starts_on, :ends_on, :grade_count
+      resolve ->(year, _) { year.terms }
+    end
+
+    resource :grades do
+      scope :year
+      summary "Grades for a school year"
+      param :term, type: :enum, values: %w[P1 P2], desc: "Half-year"
+      param :subject, desc: "Filter by subject"
+      table_fields :created_at, :subject, :value, :weight, :title
+      resolve lambda { |year, p|
+        year.grades.where(term: p[:term], subject: p[:subject]).order(:created_at)
+      }
+    end
+  end
+end

data/lib/edupage/registry.rb

@@ -0,0 +1,286 @@
+module Edupage
+  # The single description of what this tool can read.
+  #
+  # The library is hand-written and idiomatic; the CLI, the REST API and the MCP server
+  # are all generated from the declarations here. Nothing about a resource - its name,
+  # its filters, their types, what it returns - is written down more than once, so the
+  # three surfaces cannot drift apart. spec/registry_parity_spec.rb enforces that.
+  #
+  #   Registry.resource :grades do
+  #     scope   :year
+  #     summary "Grades for a school year"
+  #     param   :term, type: :enum, values: %w[P1 P2], desc: "Half-year"
+  #     resolve ->(year, p) { year.grades.where(term: p[:term]) }
+  #   end
+  class Registry
+    # Which session cursors a resource needs, and therefore which object resolves it.
+    #
+    # The scopes nest: a year implies a student, a student implies a school. Surfaces
+    # read this to build their own shape - URL segments for REST, options for the CLI,
+    # input schema properties for MCP - so a resource can never be wired up to one
+    # surface and forgotten in another.
+    # `chain` is the levels a resource actually stands on; `params` additionally carries
+    # the optional year filter that school- and student-scoped resources accept. The two
+    # differ on purpose: `students` takes `--year` to pick which year's directory to
+    # read, but it is not a year-scoped resource and must never require a student.
+    SCOPES = {
+      account: { receiver: :account, chain: [], params: [] },
+      school: { receiver: :school, chain: %i[school], params: %i[school year] },
+      student: { receiver: :student, chain: %i[school student], params: %i[school student year] },
+      year: { receiver: :year, chain: %i[school student year], params: %i[school student year] }
+    }.freeze
+
+    # Parameters implied by the scope rather than declared by the resource.
+    #
+    # school and student are required wherever they apply: no level of the chain may be
+    # skipped, and a caller that omits one is told what it could have chosen. The year is
+    # the exception - "now" is unambiguous, so it defaults to the current year and the
+    # CLI shows which one it used.
+    SCOPE_PARAMS = {
+      school: { type: :string, desc: "School origin, e.g. zsdemo", required: true },
+      student: { type: :string, desc: "Student name or id", required: true },
+      year: { type: :string, desc: "School year, e.g. 2025 (defaults to the current one)",
+              required: false }
+    }.freeze
+
+    Param = Struct.new(:name, :type, :desc, :values, :required, keyword_init: true) do
+      def enum? = type == :enum
+
+      def json_schema
+        base = case type
+               when :integer then { "type" => "integer" }
+               when :boolean then { "type" => "boolean" }
+               when :date then { "type" => "string", "format" => "date" }
+               else { "type" => "string" }
+               end
+        base["enum"] = values if enum? && values
+        base["description"] = desc if desc
+        base
+      end
+    end
+
+    # One readable thing, described once.
+    class Resource
+      attr_reader :name
+
+      def initialize(name)
+        @name = name.to_sym
+        @scope = :account
+        @summary = nil
+        @params = {}
+        @table_fields = []
+        @resolver = nil
+      end
+
+      # --- DSL ----------------------------------------------------------------------
+
+      def scope(value = nil)
+        return @scope if value.nil?
+
+        unless SCOPES.key?(value)
+          raise ArgumentError, "Unknown scope #{value.inspect}; expected one of #{SCOPES.keys.inspect}"
+        end
+
+        @scope = value
+      end
+
+      def summary(value = nil)
+        value.nil? ? @summary : (@summary = value)
+      end
+
+      def param(name, type: :string, desc: nil, values: nil, required: false)
+        @params[name.to_sym] = Param.new(name: name.to_sym, type: type, desc: desc,
+                                         values: values, required: required)
+      end
+
+      def table_fields(*fields)
+        fields.empty? ? @table_fields : (@table_fields = fields.flatten.map(&:to_sym))
+      end
+
+      def resolve(callable = nil, &block)
+        @resolver = callable || block
+      end
+
+      # --- reading ------------------------------------------------------------------
+
+      def own_params = @params.values
+
+      # Scope parameters first, then the resource's own filters.
+      def all_params
+        scope_params + own_params
+      end
+
+      def scope_params
+        SCOPES.fetch(@scope)[:params].map do |key|
+          Param.new(name: key, **SCOPE_PARAMS.fetch(key))
+        end
+      end
+
+      def receiver_kind = SCOPES.fetch(@scope)[:receiver]
+
+      # Levels of the chain this resource actually stands on, outermost first. Surfaces
+      # use it to show which school, student and year an answer came from.
+      def scope_chain = SCOPES.fetch(@scope)[:chain]
+
+      def singular? = @table_fields.empty? && name.to_s.end_with?("account")
+
+      # REST path, derived from the scope so it cannot disagree with the CLI or MCP.
+      def rest_path
+        case @scope
+        when :account then "/api/v1/#{name}"
+        when :school then "/api/v1/schools/:school/#{name}"
+        when :student then "/api/v1/schools/:school/students/:student/#{name}"
+        when :year then "/api/v1/schools/:school/students/:student/years/:year/#{name}"
+        end
+      end
+
+      def tool_name = "edupage_#{name}"
+
+      def call(context, params = {})
+        raise Error, "Resource #{name} has no resolver" unless @resolver
+
+        @resolver.call(context.receiver_for(self), normalize(params))
+      end
+
+      # Drops unknown keys and blank values so surfaces can pass their raw input.
+      def normalize(params)
+        known = all_params.map(&:name)
+        params.to_h.each_with_object({}) do |(key, value), result|
+          key = key.to_sym
+          next unless known.include?(key)
+          next if value.nil? || value.to_s.empty?
+
+          result[key] = cast(key, value)
+        end
+      end
+
+      def validate!
+        raise ArgumentError, "Resource #{name} needs a summary" if @summary.nil?
+        raise ArgumentError, "Resource #{name} needs a resolver" if @resolver.nil?
+
+        self
+      end
+
+      private
+
+      def cast(key, value)
+        param = all_params.find { |p| p.name == key }
+        case param&.type
+        when :integer then Integer(value, exception: false) || value
+        when :boolean then [true, "true", "1", 1].include?(value)
+        when :date then value.is_a?(Date) ? value : (Date.parse(value.to_s) rescue value)
+        else value
+        end
+      end
+    end
+
+    # Resolves the object a resource should be called on, from surface-level strings.
+    #
+    # This is where "--student Jana" or ".../students/113506/..." becomes a Student,
+    # once, for every surface.
+    class Context
+      def initialize(account:, school: nil, student: nil, year: nil)
+        @account = account
+        @school_ref = school
+        @student_ref = student
+        @year_ref = year
+      end
+
+      def account = @account
+
+      # Each level resolves the same way: an explicit choice wins, a single option is
+      # taken silently, and anything else is refused rather than guessed.
+      #
+      # Config defaults deliberately do not count as a choice. `default_school` is the
+      # login anchor - which *.edupage.org host to authenticate against - and letting it
+      # also decide which school's data you are reading is how you end up looking at the
+      # wrong child's school without noticing.
+      def school
+        @school ||= @account.school(@school_ref)
+      end
+
+      def student
+        @student ||= begin
+          ref = @student_ref
+          candidates = school.students
+
+          if ref.nil?
+            raise AmbiguousScopeError.new(:student, student_candidates(candidates)) if candidates.count > 1
+
+            candidates.first or raise NotFoundError, "#{school.origin} has no students for this account"
+          else
+            resolve_student(ref, candidates) or
+              raise NotFoundError, "No student #{ref.inspect}. Available: #{candidates.map(&:full_name).join(", ")}"
+          end
+        end
+      end
+
+      def year
+        @year ||= explicit_year? ? student.year(@year_ref) : student.current_year
+      end
+
+      # Whether the year came from the caller or was filled in as "now". The CLI says so
+      # in its output, because in September the current year is usually empty and the
+      # interesting data is in the previous one.
+      def year_defaulted? = !explicit_year?
+
+      def explicit_year?
+        !@year_ref.nil? && @year_ref.to_s != "current"
+      end
+
+      def receiver_for(resource)
+        public_send(resource.receiver_kind)
+      end
+
+      private
+
+      # Exact match on id or full name first, then a unique partial name match, so
+      # "--student Jana" works without typing the surname. An ambiguous prefix is an
+      # error rather than an arbitrary pick.
+      def resolve_student(ref, candidates)
+        exact = candidates.find { |student| student.matches?(ref) }
+        return exact if exact
+
+        needle = ref.to_s.downcase
+        partial = candidates.select { |student| student.full_name.downcase.include?(needle) }
+        return partial.first if partial.size == 1
+
+        if partial.size > 1
+          raise NotFoundError,
+                "#{ref.inspect} matches several students: #{partial.map(&:full_name).join(", ")}"
+        end
+
+        nil
+      end
+
+      def student_candidates(students)
+        students.map do |student|
+          { id: student.id, label: [student.full_name, student.class_name].compact.join(", ") }
+        end
+      end
+    end
+
+    class << self
+      def resources = @resources ||= {}
+
+      def resource(name, &block)
+        entry = Resource.new(name)
+        entry.instance_eval(&block)
+        resources[entry.name] = entry.validate!
+      end
+
+      def [](name) = resources[name.to_sym]
+      def all = resources.values
+      def names = resources.keys
+      def each(&block) = all.each(&block)
+
+      def fetch(name)
+        self[name] or raise NotFoundError, "Unknown resource #{name.inspect}; known: #{names.join(", ")}"
+      end
+    end
+  end
+end
+
+# Declarations reopen Registry rather than defining a constant of their own, so they sit
+# outside Zeitwerk's file-to-constant mapping and are loaded here instead.
+require_relative "registry/resources"