webuntis-api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1dcd96e7abfbd4f863336185dfbedae0aceaf43689e1ba9a8efd9f9b527fd017
+  data.tar.gz: 5bceaf819d35ade46f500e5f0dc1c4db7a07050e3fc6c6e91f1f9c4c7ae6bd98
+SHA512:
+  metadata.gz: d24bda2f99e561945d6ab560fb6b9f3df2a16098d4b838035b2d31742e31f6f90528d3684efc14a7a6c014c3ffd22d2126ecb08efae3edcc647a05500ec33362
+  data.tar.gz: 33a36b3307c68b7969b750c5869ef75c88b75b953c4a603eddba20c4f64aab78152091563b54037145342711affedf8cb68809e1ae0e01111e91f0a326ca688a

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.1.0
+
+**Initial Release**
+
+- REST calls re-authenticate when `api/token/new` refuses to mint a JWT and the call then
+  fails; the view API answers token-less requests with 404, which previously left the
+  client stuck on a dead session.
+- `rest.calendar_entry_detail` sends the numeric `elementType` the endpoint expects.
+- `rest.student_absences` defaults `student_id` to `-1` (all students); the endpoint
+  answers 500 without it.
+- `rpc.exams` defaults `exam_type_id` to `0` (every type); `getExams` rejects the call
+  without `examTypeId`.
+
+- `WebUntis::School.search` / `.find` for tenant discovery via `schoolquery2`.
+- `WebUntis::Client` with four login flows (`:rpc`, `:form`, `:secret`, `:anonymous`),
+  a cookie jar, lazy JWT minting from `api/token/new`, tenant-id resolution and
+  re-authenticate-once-and-retry on expired sessions.
+- `client.rpc`: the documented JSON-RPC API with snake_case parameters.
+- `client.rest`: the modern `api/rest/view/v1|v2|v3|v4` endpoints the web app uses,
+  plus the older cookie-only `api/...` endpoints; `timetable_entries` reads the tenant's
+  default format from `timetable/grid`.
+- `client.class_teachers` from `timetable/filter` (default) or by joining `getKlassen`
+  to `getTeachers` (`source: :rpc`).
+- `WebUntis::HTTP::NetHttp` and an injectable `WebUntis::HTTP::Fake` adapter.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meow the Cat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,241 @@
+# webuntis-api
+
+A dependency-free Ruby client for **WebUntis**, covering both API surfaces a school
+account can reach:
+
+- the documented **JSON-RPC** API at `/WebUntis/jsonrpc.do`, and
+- the **modern REST** API at `/WebUntis/api/rest/view/...` that the WebUntis web app
+  itself calls (plus the older cookie-only `/WebUntis/api/...` endpoints).
+
+Zero runtime dependencies: only `net/http`, `uri`, `json`, `securerandom`, `date`,
+`time` and `openssl` from the standard library. Ruby >= 3.2.
+
+This is the successor to the author's older `untis` gem (`UntisWorker`, JSON-RPC only,
+raw hashes and error hashes). The big behavioural change: **this gem raises instead of
+returning error hashes** - see [Errors](#errors).
+
+## Install
+
+```ruby
+gem "webuntis-api"
+```
+
+```sh
+gem install webuntis-api
+```
+
+## Quick start
+
+```ruby
+require "webuntis"
+
+client = WebUntis::Client.new(
+  school: "heidelberg-college",   # login name (preferred) or display name
+  username: ENV.fetch("WEBUNTIS_USER"),
+  password: ENV.fetch("WEBUNTIS_PASSWORD")
+  # server: "heidelberg-college.webuntis.com"  # skip the discovery round-trip
+)
+
+client.rpc.classes.each { |klasse| puts klasse["name"] }
+client.logout!
+```
+
+The client logs in lazily on the first call that needs a session, so `login!` is
+optional. `client.session` exposes `session_id`, `person_id`, `person_type`,
+`klasse_id`, `tenant_id`, `token`, `token_expires_at` and `school_year_id`.
+
+A client is not thread-safe: a re-login swaps the session and cookie jar underneath
+concurrent calls. Use one client per thread.
+
+### Finding a school
+
+```ruby
+WebUntis::School.search("Heidelberg")
+# => [#<WebUntis::School "Heidelberg College" login_name="heidelberg-college" ...>]
+
+school = WebUntis::School.find("Heidelberg College")
+school.login_name  # => "heidelberg-college"
+school.server      # => "heidelberg-college.webuntis.com"
+school.tenant_id   # => "4239400"
+school.base_url    # => "https://heidelberg-college.webuntis.com/WebUntis"
+```
+
+`find` raises `WebUntis::DiscoveryError` when nothing or more than one tenant matches;
+an exact case-insensitive hit on the display name, login name or server wins over
+partial matches.
+
+### Login flows
+
+| `login:` | Credentials | Endpoint |
+| --- | --- | --- |
+| `:rpc` (default) | `username:` + `password:` | `jsonrpc.do` `authenticate` |
+| `:form` | `username:` + `password:` | `j_spring_security_check`, verified by `api/token/new` |
+| `:secret` | `username:` + `secret:` | TOTP via `jsonrpc_intern.do?m=getUserData2017` |
+| `:anonymous` | `anonymous: true` | the same OTP flow with user `#anonymous#` |
+
+The mode is derived from the credentials you pass, so `secret:` implies `:secret` and
+`anonymous: true` implies `:anonymous`; pass `login:` to override. The constructor
+raises `ArgumentError` when the mode is unknown or its credentials are missing.
+
+## The modern REST layer
+
+`client.rest` sends `Authorization: Bearer <jwt>` (minted lazily from `api/token/new`
+and refreshed 30 s before the JWT's `exp`), `Tenant-Id`, the session cookies and
+`Accept: application/json, text/plain, */*`. Results are returned exactly as the API
+sends them (Hashes/Arrays with String keys).
+
+```ruby
+# 1. What the SPA loads first: tenant, permissions, current school year.
+data = client.rest.app_data
+data.dig("currentSchoolYear", "id")   # => 17
+
+# 2. One class's timetable for a week.
+entries = client.rest.timetable_entries(
+  resource_type: :class,     # "CLASS" / :class / WebUntis::ElementType::CLASS
+  resources: [470],
+  start: Date.new(2026, 3, 23),
+  end: Date.new(2026, 3, 27)
+)
+# GET api/rest/view/v1/timetable/entries?start=2026-03-23&end=2026-03-27&format=3
+#     &resourceType=CLASS&resources=470&periodTypes=&timetableType=STANDARD&layout=START_TIME
+# `format` defaults to the tenant's format for that resource type (`classFormat` etc.),
+# read once from api/rest/view/v1/timetable/grid; pass `format:` to override.
+
+# 3. The inbox.
+client.rest.messages["incomingMessages"]
+```
+
+Anything not wrapped is one line away:
+
+```ruby
+client.rest.get("api/rest/view/v1/timetable/entries/settings", { "format" => 2, "resourceType" => "CLASS" })
+client.rest.post("api/rest/view/v1/classreg/homework/list", { "dateRange" => { "start" => "2026-03-23", "end" => "2026-03-27" } })
+```
+
+Query values are encoded for you: Arrays join with `,`, `Date`/`Time` become
+`YYYY-MM-DD`, booleans become `true`/`false`, and `nil` values are dropped.
+
+Some endpoints are scoped to a school year; wrap those calls to send
+`X-Webuntis-Api-School-Year-Id`:
+
+```ruby
+client.with_school_year(16) { |scoped| scoped.rest.timetable_grid }
+```
+
+## The JSON-RPC layer
+
+```ruby
+client.rpc.teachers
+client.rpc.classes(school_year_id: 17)
+client.rpc.substitutions(start_date: Date.new(2026, 3, 23), end_date: Date.new(2026, 3, 27))
+
+client.rpc.timetable(
+  element_id: 470, element_type: :class,
+  start_date: Date.new(2026, 3, 23), end_date: Date.new(2026, 3, 27),
+  show_subst_text: true, teacher_fields: %w[id name longname]
+)
+
+client.rpc.call("getAnythingElse", { "someParam" => 1 })   # generic escape hatch
+```
+
+Parameters are written in snake_case and translated to the API's names
+(`school_year_id` -> `schoolyearId`, `surname` -> `sn`); raw camelCase keys are accepted
+too, and `timetable` raises `ArgumentError` for an option it does not know. Dates accept
+`Date`/`Time`/`DateTime`, `"YYYYMMDD"` / `"YYYY-MM-DD"` Strings or Integers and are
+sent as `YYYYMMDD` Integers; `nil` parameters are dropped. Element types accept
+`:teacher`, `"TEACHER"` or `WebUntis::ElementType::TEACHER`.
+
+Results are **not** transformed. Two helpers are there when you want to read them:
+
+```ruby
+WebUntis::Util.parse_date(20_260_916)  # => #<Date 2026-09-16>
+WebUntis::Util.parse_time(915)         # => [9, 15]
+```
+
+## Class teachers (Klassenlehrer)
+
+```ruby
+client.class_teachers
+# => [{ "class" => { "id" => 481, "name" => "10/1", "long_name" => "10/1" },
+#       "teachers" => [{ "id" => 187, "name" => "HOF", "long_name" => "Hoffmann", "fore_name" => nil }] }, ...]
+```
+
+Both sources return that same shape:
+
+- `source: :rest` (default) reads `api/rest/view/v1/timetable/filter?resourceType=CLASS`,
+  whose class rows carry `classTeacher1`/`classTeacher2`. The filter is scoped to one day
+  (`date:`, default today). Forenames are not part of that payload, so `fore_name` is nil.
+- `source: :rpc` joins `getKlassen`'s `teacher1`/`teacher2` against `getTeachers`
+  (teacher1 first, unknown and empty ids skipped, inactive classes filtered unless
+  `include_inactive: true`, `school_year_id:` forwarded) and raises `WebUntis::Error`
+  when the account cannot see those fields at all. Anonymous sessions get 401 from the
+  view API, so this is their only option, and it works only where the tenant grants
+  public access to `getTeachers`.
+
+`examples/class_teachers.rb` prints them one class per line:
+
+```sh
+WEBUNTIS_SCHOOL=heidelberg-college WEBUNTIS_USER=... WEBUNTIS_PASSWORD=... \
+  ruby examples/class_teachers.rb
+# 10/1  Hoffmann (HOF)
+
+ruby examples/class_teachers.rb --source rpc      # Hoffmann Luca (HOF)
+ruby examples/class_teachers.rb --settings config/settings.local.yml --json
+```
+
+`--settings` reads a YAML file with an `untis:` key holding `school_name`, `login` and
+`password`.
+
+## Errors
+
+Everything descends from `WebUntis::Error`:
+
+| Class | Raised when |
+| --- | --- |
+| `DiscoveryError` | no school, or more than one, matched the query |
+| `AuthError` | login failed, or a JWT could not be minted (`stage`, `status`) |
+| `RpcError` | a JSON-RPC response carried an `error` member (`code`, `data`, `method`) |
+| `HttpError` | an unhandled non-2xx response (`status`, `body`, `method`, `path`) |
+| `ApiError` | a 2xx REST body carried `data.error.data.messageKey` or `errorMessage` |
+
+Expired sessions are handled before they reach you: a JSON-RPC `-8520`
+("not authenticated"), a REST 401/403, a REST redirect to `index.do`, or a failed REST
+call for which `api/token/new` refused to mint a JWT makes the client log in again and
+retry the call **once**.
+
+## Testing against a fake
+
+The HTTP layer is injectable. Any object answering
+`call(method, url, headers:, body:) -> WebUntis::HTTP::Response` will do;
+`WebUntis::HTTP::Fake` is included:
+
+```ruby
+fake = WebUntis::HTTP::Fake.new
+fake.stub_json({ "jsonrpc" => "2.0", "result" => { "sessionId" => "SID" } })
+fake.stub_json({ "jsonrpc" => "2.0", "result" => [{ "id" => 1, "name" => "5a" }] })
+
+client = WebUntis::Client.new(school: "demo", server: "demo.webuntis.com",
+                              username: "u", password: "p", http: fake)
+client.rpc.classes
+fake.requests.last.json   # => {"id"=>"...", "method"=>"getKlassen", ...}
+```
+
+A block form answers per request: `WebUntis::HTTP::Fake.new { |request| ... }`.
+
+## Which API is this?
+
+- The **JSON-RPC** API is the only officially documented one. Untis publishes it for
+  schools and it changes rarely.
+- The `/WebUntis/api/rest/view/...` endpoints are the **web app's internal API**.
+  They are not documented, differ between tenants and roles, and may change without
+  notice - pin your gem version and expect to adapt.
+- The official partner **Untis Platform API** (`api.webuntis.com`, OAuth client
+  credentials, requires an integration partnership) is a different product and is
+  **out of scope** for this gem.
+
+Untis asks that applications log out as soon as they are done; server sessions are
+otherwise dropped after roughly ten minutes of idling.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/examples/class_teachers.rb

@@ -0,0 +1,66 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "yaml"
+require_relative "../lib/webuntis"
+
+options = { json: false, settings: nil, source: :rest }
+OptionParser.new do |parser|
+  parser.banner = "Usage: class_teachers.rb [options]"
+  parser.on("--settings PATH", "YAML file with an `untis:` key (school_name, login, password)") do |path|
+    options[:settings] = path
+  end
+  parser.on("--source SOURCE", %w[rest rpc],
+            "rest (default): timetable/filter classTeacher1/2; rpc: getKlassen joined with getTeachers") do |s|
+    options[:source] = s.to_sym
+  end
+  parser.on("--json", "Print the raw class_teachers result as JSON") { options[:json] = true }
+  parser.on("-h", "--help") do
+    puts parser
+    exit 0
+  end
+end.parse!
+
+settings = options[:settings] ? (YAML.safe_load_file(options[:settings])["untis"] || {}) : {}
+
+school = settings["school_name"] || ENV["WEBUNTIS_SCHOOL"] || "heidelberg-college"
+username = settings["login"] || ENV.fetch("WEBUNTIS_USER", nil)
+password = settings["password"] || ENV.fetch("WEBUNTIS_PASSWORD", nil)
+server = ENV.fetch("WEBUNTIS_SERVER", nil)
+
+abort("set WEBUNTIS_USER and WEBUNTIS_PASSWORD, or pass --settings PATH") if username.nil? || password.nil?
+
+def teacher_label(teacher)
+  name = [teacher["long_name"], teacher["fore_name"]].compact.reject(&:empty?).join(" ")
+  short = teacher["name"]
+  short.to_s.empty? ? name : "#{name} (#{short})"
+end
+
+begin
+  # A settings file may hold the display name ("Heidelberg College"); the API wants the login name.
+  if school.match?(/\s/)
+    resolved = WebUntis::School.find(school)
+    warn("resolved #{school.inspect} to #{resolved.login_name} on #{resolved.server}")
+    school = resolved.login_name
+    server ||= resolved.server
+  end
+
+  client = WebUntis::Client.new(school: school, server: server, username: username, password: password)
+  rows = client.class_teachers(source: options[:source])
+
+  if options[:json]
+    puts JSON.pretty_generate(rows)
+  else
+    rows.sort_by { |row| row.dig("class", "name").to_s }.each do |row|
+      labels = row["teachers"].map { |teacher| teacher_label(teacher) }
+      puts "#{row.dig("class", "name")}  #{labels.empty? ? "-" : labels.join(", ")}"
+    end
+  end
+rescue WebUntis::Error => e
+  warn(e.message)
+  exit 1
+ensure
+  client&.logout!
+end