webuntis-api 0.1.0

data/lib/webuntis/rpc.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module WebUntis
+  # The officially documented JSON-RPC API at `/WebUntis/jsonrpc.do`.
+  #
+  # Every method returns the raw parsed `result` payload (Hashes and Arrays with
+  # String keys) and raises {RpcError} instead of returning an error envelope.
+  class RPC
+    TIMETABLE_OPTIONS = {
+      only_base_timetable: "onlyBaseTimetable",
+      show_booking: "showBooking",
+      show_info: "showInfo",
+      show_subst_text: "showSubstText",
+      show_ls_text: "showLsText",
+      show_ls_number: "showLsNumber",
+      show_studentgroup: "showStudentgroup",
+      klasse_fields: "klasseFields",
+      room_fields: "roomFields",
+      subject_fields: "subjectFields",
+      teacher_fields: "teacherFields"
+    }.freeze
+    TIMETABLE_OPTION_KEYS = (TIMETABLE_OPTIONS.keys + TIMETABLE_OPTIONS.values.map(&:to_sym)).freeze
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Calls any JSON-RPC method and returns its `result`; nil params are dropped.
+    def call(method, params = {})
+      @client.rpc_call(method, params)
+    end
+
+    # getTeachers
+    def teachers(**extra)
+      call("getTeachers", stringify(extra))
+    end
+
+    # getStudents
+    def students(**extra)
+      call("getStudents", stringify(extra))
+    end
+
+    # getKlassen
+    def classes(school_year_id: nil, **extra)
+      call("getKlassen", { "schoolyearId" => school_year_id }.merge(stringify(extra)))
+    end
+
+    # getSubjects
+    def subjects(**extra)
+      call("getSubjects", stringify(extra))
+    end
+
+    # getRooms
+    def rooms(**extra)
+      call("getRooms", stringify(extra))
+    end
+
+    # getDepartments
+    def departments(**extra)
+      call("getDepartments", stringify(extra))
+    end
+
+    # getHolidays
+    def holidays(**extra)
+      call("getHolidays", stringify(extra))
+    end
+
+    # getTimegridUnits
+    def timegrid(**extra)
+      call("getTimegridUnits", stringify(extra))
+    end
+
+    # getStatusData
+    def status_data(**extra)
+      call("getStatusData", stringify(extra))
+    end
+
+    # getCurrentSchoolyear
+    def current_school_year(**extra)
+      call("getCurrentSchoolyear", stringify(extra))
+    end
+
+    # getSchoolyears
+    def school_years(**extra)
+      call("getSchoolyears", stringify(extra))
+    end
+
+    # getLatestImportTime, converted from milliseconds to a Time.
+    def latest_import_time(**extra)
+      value = call("getLatestImportTime", stringify(extra))
+      value.is_a?(Numeric) ? Time.at(value / 1000.0) : value
+    end
+
+    # getPersonId
+    def person_id(type: nil, surname: nil, forename: nil, birthday: 0, **extra)
+      call("getPersonId", {
+        "type" => ElementType.resolve(type),
+        "sn" => surname,
+        "fn" => forename,
+        "dob" => birthday
+      }.merge(stringify(extra)))
+    end
+
+    # getSubstitutions
+    def substitutions(start_date: nil, end_date: nil, department_id: 0, **extra)
+      call("getSubstitutions", {
+        "startDate" => Util.to_untis_date(start_date),
+        "endDate" => Util.to_untis_date(end_date),
+        "departmentId" => department_id
+      }.merge(stringify(extra)))
+    end
+
+    # getExams; `examTypeId` is mandatory and `0` returns every exam type.
+    def exams(start_date: nil, end_date: nil, exam_type_id: 0, **extra)
+      call("getExams", {
+        "examTypeId" => exam_type_id,
+        "startDate" => Util.to_untis_date(start_date),
+        "endDate" => Util.to_untis_date(end_date)
+      }.merge(stringify(extra)))
+    end
+
+    # getExamTypes
+    def exam_types(**extra)
+      call("getExamTypes", stringify(extra))
+    end
+
+    # getClassregEvents
+    def classreg_events(start_date: nil, end_date: nil, element: nil, **extra)
+      call("getClassregEvents", {
+        "startDate" => Util.to_untis_date(start_date),
+        "endDate" => Util.to_untis_date(end_date),
+        "element" => element
+      }.merge(stringify(extra)))
+    end
+
+    # getClassregCategories
+    def classreg_categories(**extra)
+      call("getClassregCategories", stringify(extra))
+    end
+
+    # getClassregCategoryGroups
+    def classreg_category_groups(**extra)
+      call("getClassregCategoryGroups", stringify(extra))
+    end
+
+    # getTimetable, always in its `options` form; only the options given are sent and unknown ones raise.
+    def timetable(element_id:, element_type:, start_date:, end_date:, key_type: "id", **options)
+      body = {
+        "element" => { "id" => element_id, "type" => ElementType.resolve(element_type), "keyType" => key_type },
+        "startDate" => Util.to_untis_date(start_date),
+        "endDate" => Util.to_untis_date(end_date)
+      }
+      call("getTimetable", { "options" => body.merge(timetable_options(options)) })
+    end
+
+    # getTimetableWithAbsences
+    def timetable_with_absences(start_date: nil, end_date: nil, **extra)
+      call("getTimetableWithAbsences", {
+             "options" => {
+               "startDate" => Util.to_untis_date(start_date),
+               "endDate" => Util.to_untis_date(end_date)
+             }.merge(stringify(extra))
+           })
+    end
+
+    private
+
+    def timetable_options(options)
+      unknown = options.keys - TIMETABLE_OPTION_KEYS
+      raise ArgumentError, "unknown getTimetable options: #{unknown.join(", ")}" unless unknown.empty?
+
+      TIMETABLE_OPTIONS.each_with_object({}) do |(snake, name), memo|
+        value = options.key?(snake) ? options[snake] : options[name.to_sym]
+        memo[name] = value unless value.nil?
+      end
+    end
+
+    def stringify(params)
+      params.transform_keys(&:to_s)
+    end
+  end
+end

data/lib/webuntis/school.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "uri"
+
+module WebUntis
+  # One WebUntis tenant as the public school search returns it.
+  class School
+    SEARCH_URL = "https://schoolsearch.webuntis.com/schoolquery2"
+
+    attr_reader :server, :login_name, :display_name, :server_url, :school_id, :tenant_id, :address
+
+    def initialize(server:, login_name: nil, display_name: nil, server_url: nil,
+                   school_id: nil, tenant_id: nil, address: nil)
+      @server = server
+      @login_name = login_name
+      @display_name = display_name
+      @server_url = server_url
+      @school_id = school_id
+      @tenant_id = tenant_id
+      @address = address
+    end
+
+    class << self
+      # Searches every WebUntis tenant via the `searchSchool` JSON-RPC method on schoolquery2.
+      def search(query, http: nil)
+        adapter = http || HTTP::NetHttp.new
+        response = adapter.call(
+          :post, SEARCH_URL,
+          headers: { "Content-Type" => "application/json", "Accept" => "application/json" },
+          body: JSON.generate(
+            "id" => SecureRandom.hex(8),
+            "method" => "searchSchool",
+            "params" => [{ "search" => query.to_s }],
+            "jsonrpc" => "2.0"
+          )
+        )
+        parse_search(response, query)
+      ensure
+        adapter.close if http.nil? && adapter.respond_to?(:close)
+      end
+
+      # Resolves a query to exactly one school, preferring an exact case-insensitive name match.
+      def find(query, http: nil)
+        candidates = search(query, http: http)
+        raise DiscoveryError.new("no WebUntis school matched #{query.inspect}", query: query) if candidates.empty?
+
+        exact = exact_matches(candidates, query)
+        return exact.first if exact.length == 1
+        raise ambiguous(query, exact) if exact.length > 1
+        return candidates.first if candidates.length == 1
+
+        raise ambiguous(query, candidates)
+      end
+
+      private
+
+      def parse_search(response, query)
+        unless response.success?
+          raise HttpError.new("school search failed with HTTP #{response.status}", status: response.status,
+                                                                                   body: response.body, method: :post,
+                                                                                   path: SEARCH_URL)
+        end
+
+        payload = response.json
+        payload = {} unless payload.is_a?(Hash)
+        if payload["error"]
+          raise DiscoveryError.new("school search failed: #{payload.dig("error", "message")}", query: query)
+        end
+
+        Array(payload.dig("result", "schools")).map { |entry| from_search_result(entry) }
+      end
+
+      def from_search_result(entry)
+        new(
+          server: entry["server"],
+          login_name: entry["loginName"],
+          display_name: entry["displayName"],
+          server_url: entry["serverUrl"],
+          school_id: entry["schoolId"],
+          tenant_id: entry["tenantId"],
+          address: entry["address"]
+        )
+      end
+
+      def exact_matches(candidates, query)
+        needle = query.to_s.strip.downcase
+        candidates.select do |school|
+          [school.display_name, school.login_name, school.server, school.server_url]
+            .compact.any? { |value| value.downcase == needle }
+        end
+      end
+
+      def ambiguous(query, candidates)
+        DiscoveryError.new(
+          "#{candidates.length} WebUntis schools matched #{query.inspect}; pass `server:` and the login name",
+          query: query,
+          matches: candidates.map { |school| "#{school.display_name} <#{school.server}>" }
+        )
+      end
+    end
+
+    # The `/WebUntis` prefix every request is built from, normalised from whatever `server` holds.
+    def base_url
+      raw = @server.to_s.strip
+      raw = "https://#{raw.sub(%r{\A/+}, "")}" unless raw.match?(%r{\Ahttps?://}i)
+      uri = URI.parse(raw)
+      raise Error, "server #{@server.inspect} has no host" if uri.host.to_s.empty?
+
+      "#{origin(uri)}#{prefix(uri)}/WebUntis"
+    rescue URI::InvalidURIError => e
+      raise Error, "server #{@server.inspect} is not a valid URL: #{e.message}"
+    end
+
+    # The school identifier sent as the `school` query parameter and the `schoolname` cookie.
+    def name
+      @login_name || @display_name || @server
+    end
+
+    # Every field of this school as a Hash.
+    def to_h
+      {
+        server: @server, login_name: @login_name, display_name: @display_name, server_url: @server_url,
+        school_id: @school_id, tenant_id: @tenant_id, address: @address
+      }
+    end
+
+    def inspect
+      "#<WebUntis::School #{@display_name.inspect} login_name=#{@login_name.inspect} server=#{@server.inspect}>"
+    end
+
+    private
+
+    def origin(uri)
+      default_port = uri.scheme == "https" ? 443 : 80
+      port = uri.port == default_port ? nil : ":#{uri.port}"
+      "#{uri.scheme}://#{uri.host}#{port}"
+    end
+
+    # The path before `/WebUntis`, if the server was given with one (`https://host/prefix/WebUntis/...`).
+    def prefix(uri)
+      uri.path.to_s.sub(%r{/WebUntis(/.*)?\z}, "").sub(%r{/+\z}, "")
+    end
+  end
+end

data/lib/webuntis/session.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module WebUntis
+  # Everything one logged-in WebUntis session carries.
+  class Session
+    attr_accessor :session_id, :person_id, :person_type, :klasse_id, :tenant_id,
+                  :token, :token_expires_at, :school_year_id, :stale_at
+
+    # True once a login has produced a session cookie.
+    def open?
+      !@session_id.nil?
+    end
+
+    # True when there is no JWT yet or the cached one is due for a refresh.
+    def token_stale?(now)
+      return true if @token.nil? || @stale_at.nil?
+
+      now >= @stale_at
+    end
+
+    # Forgets the JWT while keeping the session cookie.
+    def forget_token
+      @token = nil
+      @token_expires_at = nil
+      @stale_at = nil
+    end
+
+    def inspect
+      "#<WebUntis::Session person_id=#{@person_id.inspect} person_type=#{@person_type.inspect} " \
+        "tenant_id=#{@tenant_id.inspect} open=#{open?}>"
+    end
+  end
+end

data/lib/webuntis/totp.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module WebUntis
+  # RFC 6238 time-based one-time passwords, as the WebUntis app secret login uses them.
+  module TOTP
+    ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"
+
+    module_function
+
+    # The current 6-digit SHA1 TOTP for a base32 app secret.
+    def code(secret, at: Time.now, step: 30, digits: 6)
+      counter = at.to_i / step
+      digest = OpenSSL::HMAC.digest("SHA1", decode_base32(secret), [counter].pack("Q>"))
+      offset = digest[-1].ord & 0x0f
+      binary = digest[offset, 4].unpack1("N") & 0x7fffffff
+      format("%0#{digits}d", binary % (10**digits))
+    end
+
+    # Decodes an RFC 4648 base32 String into raw bytes.
+    def decode_base32(secret)
+      bits = secret.to_s.upcase.delete("^#{ALPHABET}").each_char.map do |char|
+        ALPHABET.index(char).to_s(2).rjust(5, "0")
+      end.join
+      [bits[0, bits.length - (bits.length % 8)].to_s].pack("B*")
+    end
+  end
+end

data/lib/webuntis/util.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module WebUntis
+  # Conversions between Ruby dates/times and the integer formats WebUntis uses.
+  module Util
+    module_function
+
+    # Converts a Date/Time/DateTime, an Integer or a "YYYYMMDD" / "YYYY-MM-DD" String to an Integer `YYYYMMDD`.
+    def to_untis_date(value)
+      return nil if value.nil?
+      return value if value.is_a?(Integer)
+      return value.strftime("%Y%m%d").to_i if value.respond_to?(:strftime)
+
+      digits = value.to_s.delete("^0-9")
+      raise Error, "cannot read #{value.inspect} as a date" unless digits.length == 8 && untis_digits?(digits)
+
+      digits.to_i
+    end
+
+    # Converts a Date/Time/DateTime, an Integer `YYYYMMDD` or a String to an ISO `YYYY-MM-DD` String.
+    def to_iso_date(value)
+      return nil if value.nil?
+      return value.strftime("%Y-%m-%d") if value.respond_to?(:strftime)
+      return parse_date(value).strftime("%Y-%m-%d") if value.is_a?(Integer) || value.to_s.match?(/\A\d{8}\z/)
+
+      value.to_s
+    end
+
+    # Converts a Time/DateTime or String to an ISO `YYYY-MM-DDTHH:MM` String.
+    def to_iso_datetime(value)
+      return nil if value.nil?
+      return value.strftime("%Y-%m-%dT%H:%M") if value.respond_to?(:hour)
+      return value.strftime("%Y-%m-%dT00:00") if value.respond_to?(:strftime)
+
+      value.to_s
+    end
+
+    # Recursively drops nil values from a params Hash (JSON-RPC rejects explicit nulls).
+    def compact_params(params)
+      case params
+      when Hash
+        params.each_with_object({}) do |(key, value), memo|
+          next if value.nil?
+
+          memo[key.is_a?(Symbol) ? key.to_s : key] = compact_params(value)
+        end
+      when Array then params.map { |entry| compact_params(entry) }
+      else params
+      end
+    end
+
+    # Parses an Untis `YYYYMMDD` date (Integer or String) into a Date.
+    def parse_date(value)
+      Date.strptime(value.to_s.rjust(8, "0"), "%Y%m%d")
+    end
+
+    # Parses an Untis `Hmm` time (Integer or String) into a `[hour, minute]` pair.
+    def parse_time(value)
+      digits = value.to_s.rjust(4, "0")
+      [digits[0, 2].to_i, digits[2, 2].to_i]
+    end
+
+    # Base64-encodes a String without newlines.
+    def base64(value)
+      [value.to_s].pack("m0")
+    end
+
+    # Decodes a base64url segment such as a JWT payload.
+    def base64url_decode(value)
+      padded = value.tr("-_", "+/")
+      padded += "=" * ((4 - (padded.length % 4)) % 4)
+      padded.unpack1("m0")
+    end
+
+    def untis_digits?(digits)
+      Date.strptime(digits, "%Y%m%d")
+      true
+    rescue Date::Error
+      false
+    end
+  end
+end

data/lib/webuntis/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module WebUntis
+  VERSION = "0.1.0"
+end

data/lib/webuntis.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "date"
+require "json"
+require "securerandom"
+require "time"
+require "uri"
+
+require_relative "webuntis/version"
+require_relative "webuntis/errors"
+require_relative "webuntis/util"
+require_relative "webuntis/element_type"
+require_relative "webuntis/http"
+require_relative "webuntis/cookie_jar"
+require_relative "webuntis/school"
+require_relative "webuntis/totp"
+require_relative "webuntis/session"
+require_relative "webuntis/rpc"
+require_relative "webuntis/rest"
+require_relative "webuntis/client"
+
+# A Ruby client for the WebUntis JSON-RPC API and the modern REST API of the
+# WebUntis web app.
+module WebUntis
+  # Builds a {Client}; see {Client#initialize} for the options.
+  def self.client(**)
+    Client.new(**)
+  end
+end

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification
+name: webuntis-api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Meow the Cat
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A dependency-free Ruby client for the WebUntis JSON-RPC API and the modern
+  /WebUntis/api/rest/view endpoints used by the WebUntis web app.
+email:
+- meowdakat@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- examples/class_teachers.rb
+- lib/webuntis.rb
+- lib/webuntis/client.rb
+- lib/webuntis/cookie_jar.rb
+- lib/webuntis/element_type.rb
+- lib/webuntis/errors.rb
+- lib/webuntis/http.rb
+- lib/webuntis/http/fake.rb
+- lib/webuntis/http/net_http.rb
+- lib/webuntis/rest.rb
+- lib/webuntis/rpc.rb
+- lib/webuntis/school.rb
+- lib/webuntis/session.rb
+- lib/webuntis/totp.rb
+- lib/webuntis/util.rb
+- lib/webuntis/version.rb
+homepage: https://github.com/Meow/webuntis-api
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/Meow/webuntis-api
+  changelog_uri: https://github.com/Meow/webuntis-api/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: WebUntis API client
+test_files: []