webuntis-api 0.1.0

data/lib/webuntis/http/fake.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module WebUntis
+  module HTTP
+    # A test adapter: replays queued stubs (or a block) and records every request in {#requests}.
+    class Fake
+      attr_reader :requests, :stubs
+
+      def initialize(stubs = [], &block)
+        @stubs = Array(stubs)
+        @block = block
+        @requests = []
+      end
+
+      # Queues one more stub: a {Response}, or a callable taking the {Request}.
+      def stub(response = nil, status: 200, body: "", headers: {}, &block)
+        @stubs << (response || block || Response.new(status: status, body: body, headers: headers))
+        self
+      end
+
+      # Queues a JSON response stub.
+      def stub_json(payload, status: 200, headers: {})
+        stub(Response.new(status: status, body: JSON.generate(payload),
+                          headers: { "content-type" => "application/json" }.merge(headers)))
+      end
+
+      # Records the request and answers it from the block or the next queued stub.
+      def call(method, url, headers: {}, body: nil)
+        request = Request.new(method: method, url: url, headers: headers, body: body)
+        @requests << request
+        return @block.call(request) if @block
+
+        stub = @stubs.shift
+        raise Error, "WebUntis::HTTP::Fake ran out of stubs for #{method.to_s.upcase} #{url}" if stub.nil?
+
+        stub.respond_to?(:call) ? stub.call(request) : stub
+      end
+
+      # The last recorded request.
+      def last_request
+        @requests.last
+      end
+    end
+  end
+end

data/lib/webuntis/http/net_http.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module WebUntis
+  module HTTP
+    # The default adapter: one persistent `Net::HTTP` connection per host, TLS on, no redirect following.
+    class NetHttp
+      REQUEST_CLASSES = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        put: Net::HTTP::Put,
+        delete: Net::HTTP::Delete
+      }.freeze
+
+      def initialize(open_timeout: 10, read_timeout: 30)
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+        @connections = {}
+        @mutex = Mutex.new
+      end
+
+      # Performs one request and returns a {Response}; 3xx responses are returned, never followed.
+      def call(method, url, headers: {}, body: nil)
+        uri = URI.parse(url)
+        request = build_request(method, uri, headers, body)
+        response = @mutex.synchronize { perform(uri, request) }
+        Response.new(status: response.code, body: response.body.to_s, headers: response_headers(response))
+      end
+
+      # Closes every pooled connection.
+      def close
+        @mutex.synchronize do
+          @connections.each_value { |connection| connection.finish if connection.started? }
+          @connections.clear
+        end
+      end
+
+      private
+
+      # A pooled connection the server closed in the meantime fails once; reconnect and retry.
+      def perform(uri, request, retried: false)
+        connection_for(uri).request(request)
+      rescue IOError, Errno::ECONNRESET, Errno::EPIPE
+        raise if retried
+
+        drop_connection(uri)
+        perform(uri, request, retried: true)
+      end
+
+      def drop_connection(uri)
+        connection = @connections.delete(connection_key(uri))
+        connection.finish if connection&.started?
+      rescue IOError
+        nil
+      end
+
+      def connection_key(uri)
+        [uri.scheme, uri.host, uri.port]
+      end
+
+      def build_request(method, uri, headers, body)
+        klass = REQUEST_CLASSES.fetch(method.to_s.downcase.to_sym) { raise Error, "unsupported method #{method}" }
+        request = klass.new(uri.request_uri)
+        headers.each { |key, value| request[key.to_s] = value.to_s unless value.nil? }
+        request.body = body if body
+        request
+      end
+
+      def connection_for(uri)
+        key = connection_key(uri)
+        connection = @connections[key]
+        return connection if connection&.started?
+
+        connection = Net::HTTP.new(uri.host, uri.port)
+        connection.use_ssl = uri.scheme == "https"
+        connection.open_timeout = @open_timeout
+        connection.read_timeout = @read_timeout
+        connection.start
+        @connections[key] = connection
+      end
+
+      def response_headers(response)
+        response.each_header.with_object({}) do |(key, _), memo|
+          name = key.downcase
+          fields = response.get_fields(key) || []
+          memo[name] = name == "set-cookie" ? fields : fields.join(", ")
+        end
+      end
+    end
+  end
+end

data/lib/webuntis/http.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module WebUntis
+  # Transport plumbing: an adapter is anything answering
+  # `call(method, url, headers:, body:)` with a {Response}.
+  module HTTP
+    # One HTTP response, as every adapter must return it.
+    class Response
+      attr_reader :status, :headers, :body
+
+      def initialize(status:, body: "", headers: {})
+        @status = status.to_i
+        @body = body.to_s
+        @headers = headers.each_with_object({}) { |(key, value), memo| memo[key.to_s.downcase] = value }
+      end
+
+      # All `Set-Cookie` values of this response.
+      def set_cookies
+        Array(@headers["set-cookie"])
+      end
+
+      # The `Location` header, if any.
+      def location
+        value = @headers["location"]
+        value.is_a?(Array) ? value.first : value
+      end
+
+      # True for 2xx responses.
+      def success?
+        (200..299).cover?(@status)
+      end
+
+      # True for 3xx responses.
+      def redirect?
+        (300..399).cover?(@status)
+      end
+
+      # The response body parsed as JSON, or the raw String when it is not JSON.
+      def json
+        return @body if @body.strip.empty?
+
+        JSON.parse(@body)
+      rescue JSON::ParserError
+        @body
+      end
+    end
+
+    # One recorded request, as {Fake} exposes it.
+    class Request
+      attr_reader :method, :url, :headers, :body
+
+      def initialize(method:, url:, headers: {}, body: nil)
+        @method = method
+        @url = url
+        @headers = headers
+        @body = body
+      end
+
+      # The query string of the request URL as a Hash of String pairs.
+      def query
+        URI.decode_www_form(URI.parse(@url).query.to_s).to_h
+      end
+
+      # The request body parsed as JSON.
+      def json
+        JSON.parse(@body.to_s)
+      end
+
+      # The path of the request URL.
+      def path
+        URI.parse(@url).path
+      end
+    end
+  end
+end
+
+require_relative "http/net_http"
+require_relative "http/fake"

data/lib/webuntis/rest.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+require "uri"
+
+module WebUntis
+  # The modern REST API the WebUntis web app uses (`/WebUntis/api/rest/view/...`)
+  # plus the older `/WebUntis/api/...` endpoints that only need session cookies.
+  #
+  # Paths are relative to `<base>/`; every method returns parsed JSON with String keys.
+  class REST
+    VIEW = "api/rest/view"
+    RANGE_KEYS = %i[start end start_date end_date].freeze
+    FORMAT_KEYS = {
+      "CLASS" => "classFormat",
+      "TEACHER" => "teacherFormat",
+      "SUBJECT" => "subjectFormat",
+      "ROOM" => "roomFormat",
+      "STUDENT" => "studentFormat"
+    }.freeze
+
+    class << self
+      # Builds a query string: arrays join with `,`, dates become `YYYY-MM-DD`, nils are dropped.
+      def encode_query(query)
+        pairs = (query || {}).filter_map do |key, value|
+          next if value.nil?
+
+          [key.to_s, format_value(value)]
+        end
+        URI.encode_www_form(pairs)
+      end
+
+      # Formats one query value.
+      def format_value(value)
+        case value
+        when Array then value.map { |entry| format_value(entry) }.join(",")
+        when Date, Time then value.strftime("%Y-%m-%d")
+        else value.to_s
+        end
+      end
+    end
+
+    def initialize(client)
+      @client = client
+    end
+
+    # GET any path relative to `<base>/`.
+    def get(path, query = {})
+      @client.rest_request(:get, path, query: query)
+    end
+
+    # POST any path relative to `<base>/`, with a JSON body.
+    def post(path, body = nil, query: {})
+      @client.rest_request(:post, path, query: query, body: body)
+    end
+
+    # PUT any path relative to `<base>/`, with a JSON body.
+    def put(path, body = nil, query: {})
+      @client.rest_request(:put, path, query: query, body: body)
+    end
+
+    # DELETE any path relative to `<base>/`.
+    def delete(path, query = {})
+      @client.rest_request(:delete, path, query: query)
+    end
+
+    # GET api/rest/view/v1/app/data
+    def app_data = get("#{VIEW}/v1/app/data")
+
+    # GET api/rest/view/v2/home
+    def home = get("#{VIEW}/v2/home")
+
+    # GET api/rest/view/v3/mobile/data
+    def mobile_data = get("#{VIEW}/v3/mobile/data")
+
+    # GET api/rest/view/v1/schoolyears
+    def school_years = get("#{VIEW}/v1/schoolyears")
+
+    # POST api/rest/view/v1/session/status
+    def session_status(client_time_zone: nil)
+      post("#{VIEW}/v1/session/status", { "clientTimeZone" => client_time_zone }.compact)
+    end
+
+    # GET api/rest/view/v1/today/meta
+    def today_meta = get("#{VIEW}/v1/today/meta")
+
+    # GET api/rest/view/v1/dashboard/cards
+    def dashboard_cards = get("#{VIEW}/v1/dashboard/cards")
+
+    # GET api/rest/view/v1/messages/status
+    def messages_status = get("#{VIEW}/v1/messages/status")
+
+    # GET api/rest/view/v1/timegrid
+    def timegrid = get("#{VIEW}/v1/timegrid")
+
+    # GET api/rest/view/v1/timetable/grid
+    def timetable_grid(timetable_type: "STANDARD")
+      get("#{VIEW}/v1/timetable/grid", { "timetableType" => timetable_type })
+    end
+
+    # GET api/rest/view/v1/timetable/filter
+    def timetable_filter(resource_type:, timetable_type: "STANDARD", **range)
+      start_date, end_date = bounds(range)
+      get("#{VIEW}/v1/timetable/filter", {
+            "resourceType" => ElementType.label(resource_type),
+            "timetableType" => timetable_type,
+            "start" => start_date,
+            "end" => end_date
+          })
+    end
+
+    # GET api/rest/view/v1/timetable/entries; `format` defaults to {#default_format}.
+    def timetable_entries(resource_type:, resources:, format: nil, period_types: "",
+                          timetable_type: "STANDARD", layout: "START_TIME", **range)
+      start_date, end_date = bounds(range)
+      get("#{VIEW}/v1/timetable/entries", {
+            "start" => start_date,
+            "end" => end_date,
+            "format" => format || default_format(resource_type),
+            "resourceType" => ElementType.label(resource_type),
+            "resources" => Array(resources),
+            "periodTypes" => period_types,
+            "timetableType" => timetable_type,
+            "layout" => layout
+          })
+    end
+
+    # The tenant's timetable format id for a resource type, read once from `timetable/grid`.
+    def default_format(resource_type)
+      label = ElementType.label(resource_type)
+      @default_formats ||= {}
+      @default_formats[label] ||= timetable_grid[FORMAT_KEYS.fetch(label)] ||
+                                  raise(Error, "timetable/grid did not report a format for #{label}")
+    end
+
+    # GET api/rest/view/v1/timetable/entriesWeekOverview
+    def timetable_week_overview(resource_type:, resources:, timetable_type: nil, **range)
+      start_date, end_date = bounds(range)
+      get("#{VIEW}/v1/timetable/entriesWeekOverview", {
+            "start" => start_date,
+            "end" => end_date,
+            "resourceType" => ElementType.label(resource_type),
+            "resources" => Array(resources),
+            "timetableType" => timetable_type
+          })
+    end
+
+    # GET api/rest/view/v1/timetable/search
+    def timetable_search(query:, school_year_id:)
+      get("#{VIEW}/v1/timetable/search", { "q" => query, "schoolyear" => school_year_id })
+    end
+
+    # GET api/rest/view/v1/timetable/menu
+    def timetable_menu = get("#{VIEW}/v1/timetable/menu")
+
+    # GET api/rest/view/v1/timetable/calendar
+    def timetable_calendar(my_timetable: false, timetable_type: "STANDARD")
+      get("#{VIEW}/v1/timetable/calendar", { "myTimetable" => my_timetable, "timetableType" => timetable_type })
+    end
+
+    # GET api/rest/view/v2/timetable/availableRooms
+    def available_rooms(start_date_time:, end_date_time:)
+      get("#{VIEW}/v2/timetable/availableRooms", {
+            "startDateTime" => Util.to_iso_datetime(start_date_time),
+            "endDateTime" => Util.to_iso_datetime(end_date_time)
+          })
+    end
+
+    # GET api/rest/view/v2/calendar-entry/detail; this endpoint takes the numeric element type.
+    def calendar_entry_detail(element_id:, element_type:, start_date_time:, end_date_time:, homework_option: "DUE")
+      get("#{VIEW}/v2/calendar-entry/detail", {
+            "elementId" => element_id,
+            "elementType" => ElementType.resolve(element_type),
+            "startDateTime" => Util.to_iso_datetime(start_date_time),
+            "endDateTime" => Util.to_iso_datetime(end_date_time),
+            "homeworkOption" => homework_option
+          })
+    end
+
+    # GET api/rest/view/v1/teachers
+    def teachers(query = {}) = get("#{VIEW}/v1/teachers", query)
+
+    # GET api/rest/view/v1/students
+    def students(query = {}) = get("#{VIEW}/v1/students", query)
+
+    # GET api/rest/view/v1/subjects
+    def subjects(query = {}) = get("#{VIEW}/v1/subjects", query)
+
+    # GET api/rest/view/v1/rooms
+    def rooms(query = {}) = get("#{VIEW}/v1/rooms", query)
+
+    # GET api/rest/view/v1/students/overview
+    def students_overview(query = {}) = get("#{VIEW}/v1/students/overview", query)
+
+    # GET api/rest/view/v1/teachers/{id}
+    def teacher(id) = get("#{VIEW}/v1/teachers/#{id}")
+
+    # GET api/rest/view/v1/students/{id}
+    def student(id) = get("#{VIEW}/v1/students/#{id}")
+
+    # GET api/rest/view/v1/students/{id}/lessons
+    def student_lessons(id) = get("#{VIEW}/v1/students/#{id}/lessons")
+
+    # GET api/rest/view/v1/students/{id}/class-history
+    def student_class_history(id) = get("#{VIEW}/v1/students/#{id}/class-history")
+
+    # GET api/rest/view/v1/messages
+    def messages = get("#{VIEW}/v1/messages")
+
+    # GET api/rest/view/v1/messages/{id}
+    def message(id) = get("#{VIEW}/v1/messages/#{id}")
+
+    # GET api/rest/view/v1/messages/sent
+    def sent_messages = get("#{VIEW}/v1/messages/sent")
+
+    # GET api/rest/view/v1/messages/drafts
+    def drafts = get("#{VIEW}/v1/messages/drafts")
+
+    # GET api/rest/view/v1/messages/permissions
+    def message_permissions = get("#{VIEW}/v1/messages/permissions")
+
+    # GET api/rest/view/v1/exams
+    def exams(with_deleted: false, **range)
+      start_date, end_date = bounds(range)
+      get("#{VIEW}/v1/exams", { "start" => start_date, "end" => end_date, "withDeleted" => with_deleted })
+    end
+
+    # GET api/rest/view/v1/exams/filter
+    def exams_filter(**range)
+      start_date, end_date = bounds(range, required: false)
+      get("#{VIEW}/v1/exams/filter", { "start" => start_date, "end" => end_date })
+    end
+
+    # GET api/rest/view/v1/exams/statistics
+    def exam_statistics(**range)
+      start_date, end_date = bounds(range)
+      get("#{VIEW}/v1/exams/statistics", { "start" => start_date, "end" => end_date })
+    end
+
+    # GET api/rest/view/v1/exam-types
+    def exam_types_v1 = get("#{VIEW}/v1/exam-types")
+
+    # GET api/rest/view/v1/classreg/homework/meta
+    def homework_meta = get("#{VIEW}/v1/classreg/homework/meta")
+
+    # POST api/rest/view/v1/classreg/homework/list
+    def homework_list(body) = post("#{VIEW}/v1/classreg/homework/list", body)
+
+    # GET api/rest/view/v4/classreg/absences
+    def absences(query = {}) = get("#{VIEW}/v4/classreg/absences", query)
+
+    # GET api/rest/view/v1/classreg/open-periods
+    def open_periods(query = {}) = get("#{VIEW}/v1/classreg/open-periods", query)
+
+    # GET api/public/timetable/weekly/data (legacy; ISO date)
+    def weekly_timetable(element_type:, element_id:, date:, format_id: 1)
+      get("api/public/timetable/weekly/data", {
+            "elementType" => ElementType.resolve(element_type),
+            "elementId" => element_id,
+            "date" => Util.to_iso_date(date),
+            "formatId" => format_id
+          })
+    end
+
+    # GET api/public/news/newsWidgetData (legacy)
+    def news_widget(date:)
+      get("api/public/news/newsWidgetData", { "date" => Util.to_untis_date(date) })
+    end
+
+    # GET api/homeworks/lessons (legacy)
+    def homeworks(start_date:, end_date:)
+      get("api/homeworks/lessons", {
+            "startDate" => Util.to_untis_date(start_date),
+            "endDate" => Util.to_untis_date(end_date)
+          })
+    end
+
+    # GET api/exams (legacy)
+    def legacy_exams(start_date:, end_date:, klasse_id: nil, with_grades: false)
+      get("api/exams", {
+            "startDate" => Util.to_untis_date(start_date),
+            "endDate" => Util.to_untis_date(end_date),
+            "klasseId" => klasse_id,
+            "withGrades" => with_grades
+          })
+    end
+
+    # GET api/classreg/absences/students (legacy); `-1` means every student / every excuse status.
+    def student_absences(start_date:, end_date:, student_id: -1, excuse_status_id: -1)
+      get("api/classreg/absences/students", {
+            "startDate" => Util.to_untis_date(start_date),
+            "endDate" => Util.to_untis_date(end_date),
+            "studentId" => student_id,
+            "excuseStatusId" => excuse_status_id
+          })
+    end
+
+    # GET api/app/config (legacy)
+    def app_config = get("api/app/config")
+
+    # GET api/daytimetable/config (legacy)
+    def daytimetable_config = get("api/daytimetable/config")
+
+    private
+
+    def bounds(range, required: true)
+      unknown = range.keys - RANGE_KEYS
+      raise ArgumentError, "unknown keywords: #{unknown.join(", ")}" unless unknown.empty?
+
+      start_value = range[:start] || range[:start_date]
+      end_value = range[:end] || range[:end_date]
+      missing = { start: start_value, end: end_value }.filter_map { |name, value| name if value.nil? }
+      raise ArgumentError, "missing keywords: #{missing.join(", ")}" if required && !missing.empty?
+
+      [Util.to_iso_date(start_value), Util.to_iso_date(end_value)]
+    end
+  end
+end