# Schnellstart: ein Lernwerkzeug andocken

Vom leeren Ordner zu einem Werkzeug, das in Stundentakt startet, die Person anmeldet, seine Aufgabe lädt, einen
Zwischenstand speichert und abgibt. Eine einzige HTML-Datei, kein Server-Code, keine Bibliothek. Begriffe in
`/docs/developers/overview.md`, alle Einzelheiten in `/docs/developers/reference.md`.

Im Folgenden steht `https://stundentakt.eu` für die Stundentakt-Instanz; bei einer anderen Instanz deren Adresse.

## 1 Was das Werkzeug braucht

- Eine Seite unter einer festen Adresse, z. B. `https://werkzeug.example/` (zum Ausprobieren
  `http://localhost:8080/`, siehe Abschnitt 4). Diese Adresse ist zugleich **Start-Adresse** und
  **Rücksprungadresse** für OAuth.
- Die Seite muss sich von `https://stundentakt.eu` einrahmen lassen: kein `X-Frame-Options: DENY`, und wenn sie
  eine Content Security Policy setzt, nennt `frame-ancestors` Stundentakt.
- Sie ruft die API mit `fetch` ohne Cookies auf. Stundentakt erlaubt CORS genau für die Origin der
  Start-Adresse (Schema, Host, Port).

## 2 Eintragen

1. In Stundentakt als Lehrer:in anmelden, im Profilmenü **Lernwerkzeuge** öffnen (`/tools`), **Lernwerkzeug
   hinzufügen**.
2. Ausfüllen:
   - **Name:** z. B. „Mein Werkzeug“.
   - **Startadresse** (`launch_url`): `https://werkzeug.example/` – `https://` Pflicht, `http://` nur für
     `localhost`, `127.0.0.1`, `[::1]`; ohne `#`, ohne Benutzer:in/Passwort.
   - **Rücksprungadressen** (`redirect_uris`), eine je Zeile, bis zu 10: hier dieselbe Adresse
     `https://werkzeug.example/`. Der Wert von `redirect_uri` im Code muss **genau** einer Zeile entsprechen.
   - **Anzeige:** „In der Seite“ (`inline`, Rahmen) oder „In eigenem Tab“ (`full`).
3. **Lernwerkzeug speichern.** In der Liste steht unter der Startadresse die **Client-ID** (`client_id`, eine UUID).
   Sie ist öffentlich; ein Secret gibt es nicht.

Ein Werkzeug gehört der Lehrer:in, die es einträgt, und steht nur ihr zur Verfügung; Werkzeuge für alle trägt der
Betreiber ein (`/docs/teachers/tools.md`).

## 3 Die Seite

Als `index.html` speichern, `STUNDENTAKT` und `CLIENT_ID` oben anpassen. Die Seite kann den Modus `learn`:

1. Start-Parameter (`mode`, `assignment`, `block`, `lang`) in `sessionStorage` merken – der OAuth-Rücksprung
   kommt ohne sie zurück.
2. PKCE erzeugen (`code_verifier` und `code_challenge` mit SHA-256) und still anmelden: Navigation zu
   `/oauth/authorize?…&prompt=none`. Stundentakt springt mit `?code=…&state=…` zurück (oder mit
   `?error=login_required`, wenn niemand angemeldet ist: dann ein Knopf, der ohne `prompt` anmeldet).
3. Code gegen Tokens tauschen (`POST /oauth/token`), Tokens in `sessionStorage`.
4. `GET me` (wer), `GET assignments/{a}` (Aufgabe), `GET …/draft` (Zwischenstand und frühere Abgabe).
5. Speichern mit `PUT …/draft`, Abgeben mit `POST …/response`.
6. Bei `token_expired` mit dem Erneuerungstoken erneuern; bei `token_revoked`/`token_invalid` still neu anmelden.
7. Seine Höhe per `postMessage` an den Rahmen melden.

```html
<!doctype html>
<html lang="de">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Mein Werkzeug</title>
  <style>
    body { font: 16px/1.5 system-ui, sans-serif; margin: 1rem; }
    textarea { width: 100%; min-height: 8rem; box-sizing: border-box; }
    #status { color: #555; }
  </style>
</head>
<body>
  <h1 id="title">Lädt …</h1>
  <p id="task"></p>
  <p id="who"></p>
  <textarea id="work" hidden></textarea>
  <p>
    <button id="save" hidden>Zwischenstand speichern</button>
    <button id="submit" hidden>Abgeben</button>
    <button id="signin" hidden>In Stundentakt anmelden</button>
  </p>
  <p id="status" role="status"></p>

  <script type="module">
    // ── Einstellungen ────────────────────────────────────────────────────────────
    const STUNDENTAKT = 'https://stundentakt.eu';           // ohne Schrägstrich am Ende
    const CLIENT_ID = '00000000-0000-0000-0000-000000000000';               // steht am Eintrag unter /tools
    const REDIRECT_URI = location.origin + location.pathname; // genau so als Rücksprungadresse eintragen
    const API = STUNDENTAKT + '/api/v1/tools';
    const SCOPE = 'tools:write';

    const $ = (id) => document.getElementById(id);
    const status = (text) => { $('status').textContent = text; reportHeight(); };

    // ── Höhe an Stundentakt melden (nur im Rahmen wirksam) ───────────────────────
    function reportHeight() {
      if (window.parent === window) return;
      const height = Math.min(20000, Math.max(1, Math.ceil(document.documentElement.scrollHeight)));
      window.parent.postMessage({ source: 'stundentakt-lernobjekt', v: 1, type: 'height', height }, '*');
    }
    new ResizeObserver(reportHeight).observe(document.body);

    // ── Start-Parameter merken: der OAuth-Rücksprung kommt ohne sie zurück ──────
    const query = new URLSearchParams(location.search);
    if (query.has('mode')) {
      sessionStorage.setItem('launch', JSON.stringify(Object.fromEntries(query)));
    }
    const launch = JSON.parse(sessionStorage.getItem('launch') || 'null');
    const lang = launch?.lang === 'en' ? 'en' : 'de';

    // ── PKCE ─────────────────────────────────────────────────────────────────────
    const base64url = (bytes) => btoa(String.fromCharCode(...bytes))
      .replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');

    async function authorizeUrl(silent) {
      const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
      const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
      const state = base64url(crypto.getRandomValues(new Uint8Array(16)));
      sessionStorage.setItem('pkce', JSON.stringify({ verifier, state }));
      const params = new URLSearchParams({
        client_id: CLIENT_ID, redirect_uri: REDIRECT_URI, response_type: 'code', scope: SCOPE, state,
        code_challenge: base64url(new Uint8Array(digest)), code_challenge_method: 'S256',
      });
      if (silent) params.set('prompt', 'none');
      return STUNDENTAKT + '/oauth/authorize?' + params;
    }

    // ── Tokens ───────────────────────────────────────────────────────────────────
    const tokens = () => JSON.parse(sessionStorage.getItem('tokens') || 'null');

    async function tokenRequest(body) {
      const response = await fetch(STUNDENTAKT + '/oauth/token', {
        method: 'POST', credentials: 'omit',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
        body: new URLSearchParams({ client_id: CLIENT_ID, ...body }),
      });
      if (!response.ok) return false;
      const json = await response.json();
      sessionStorage.setItem('tokens', JSON.stringify({ access: json.access_token, refresh: json.refresh_token }));
      return true;
    }

    async function exchangeCode(code, state) {
      const pkce = JSON.parse(sessionStorage.getItem('pkce') || 'null');
      sessionStorage.removeItem('pkce');
      if (!pkce || pkce.state !== state) return false;
      return tokenRequest({
        grant_type: 'authorization_code', redirect_uri: REDIRECT_URI, code, code_verifier: pkce.verifier,
      });
    }

    const refresh = () => tokens()?.refresh
      ? tokenRequest({ grant_type: 'refresh_token', refresh_token: tokens().refresh })
      : Promise.resolve(false);

    // Neu anmelden: still (prompt=none). Die Seite wird dabei verlassen und kommt mit ?code=… zurück.
    async function signInSilently() {
      sessionStorage.removeItem('tokens');
      location.href = await authorizeUrl(true);
      return new Promise(() => {}); // die Navigation läuft
    }

    // ── API-Aufruf mit Erneuern ──────────────────────────────────────────────────
    async function api(method, path, body) {
      for (let attempt = 0; attempt < 2; attempt++) {
        const response = await fetch(API + path, {
          method, credentials: 'omit',
          headers: {
            Authorization: 'Bearer ' + tokens()?.access, Accept: 'application/json', 'Accept-Language': lang,
            ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
          },
          body: body === undefined ? undefined : JSON.stringify(body),
        });
        if (response.status === 204) return null;
        const json = await response.json();
        if (response.ok) return json;

        if (json.reason === 'token_expired' && attempt === 0 && await refresh()) continue;
        if (['token_expired', 'token_revoked', 'token_invalid'].includes(json.reason)) return signInSilently();
        if (json.reason === 'too_many_requests' || json.reason === 'maintenance') {
          const seconds = Number(response.headers.get('Retry-After') || 5);
          await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
          continue;
        }
        throw Object.assign(new Error(json.message), { reason: json.reason, body: json, status: response.status });
      }
      throw new Error('Stundentakt antwortet nicht.');
    }

    // ── Ablauf ───────────────────────────────────────────────────────────────────
    async function main() {
      // a) Rücksprung von /oauth/authorize
      if (query.has('code') || query.has('error')) {
        history.replaceState(null, '', REDIRECT_URI);
        if (query.get('error') === 'login_required' || query.get('error') === 'interaction_required') {
          return offerSignIn();
        }
        if (query.has('error')) {
          return status('Anmeldung abgelehnt: ' + query.get('error') + ' ' + (query.get('reason') || ''));
        }
        if (!await exchangeCode(query.get('code'), query.get('state'))) {
          return status('Der Code ließ sich nicht eintauschen.');
        }
        if (window.opener && sessionStorage.getItem('popup')) return window.close();
      }

      // b) ohne Start-Parameter weiß das Werkzeug nicht, welche Aufgabe gemeint ist
      if (!launch) return status('Bitte das Werkzeug aus Stundentakt heraus öffnen.');

      // c) noch kein Token: still anmelden
      if (!tokens()) return signInSilently();

      // d) arbeiten
      const me = await api('GET', '/me');
      $('who').textContent = 'Angemeldet als ' + me.alias + ' (' + me.kind + ')';

      if (launch.mode !== 'learn') return status('Dieses Beispiel kann nur den Modus learn.');

      const lesson = await api('GET', '/assignments/' + launch.assignment);
      const block = lesson.blocks.find((b) => b.ulid === launch.block);
      $('title').textContent = block.payload.title || 'Aufgabe';
      $('task').textContent = block.payload.task?.text || '';

      const saved = await api('GET', '/assignments/' + launch.assignment + '/blocks/' + launch.block + '/draft');
      $('work').value = (saved.draft ?? saved.response?.payload)?.state?.text ?? '';
      $('work').hidden = false;

      if (lesson.window.takes_answers) {
        $('save').hidden = $('submit').hidden = false;
      } else {
        $('work').readOnly = true;
        status('Die Klasse nimmt gerade keine Antwort an.');
      }
      if (saved.response) status('Schon abgegeben' + (saved.draft ? ', danach weitergearbeitet.' : '.'));
    }

    // Niemand angemeldet: ein Klick öffnet die Anmeldung. Im Rahmen in einem neuen Fenster, danach erneut still.
    function offerSignIn() {
      status('Bitte in Stundentakt anmelden.');
      $('signin').hidden = false;
      $('signin').onclick = async () => {
        const url = await authorizeUrl(false);
        if (window.parent === window) {
          location.href = url;
          return;
        }
        sessionStorage.setItem('popup', '1');
        window.open(url, '_blank');
        sessionStorage.removeItem('popup');
        window.addEventListener('focus', () => signInSilently(), { once: true });
      };
    }

    const draftPath = () => '/assignments/' + launch.assignment + '/blocks/' + launch.block + '/draft';

    $('save').onclick = async () => {
      await api('PUT', draftPath(), { state: { text: $('work').value } });
      status('Zwischenstand gespeichert.');
    };

    $('submit').onclick = async () => {
      try {
        await api('POST', '/assignments/' + launch.assignment + '/blocks/' + launch.block + '/response',
          { done: true, state: { text: $('work').value } });
        status('Abgegeben.');
      } catch (error) {
        status(error.reason === 'not_open' ? 'Die Abgabe ist gerade nicht offen (' + error.body.detail + ').' : error.message);
      }
    };

    main().catch((error) => status('Fehler: ' + (error.reason || error.message)));
  </script>
</body>
</html>
```

Was die Aufgabe enthält, bestimmt das Werkzeug selbst: `task` ist beliebiges JSON. Dieses Beispiel erwartet
`{"text": "…"}` und speichert seinen Stand als `{"text": "…"}`. Wie eine Lehrer:in die Aufgabe im Werkzeug schreibt
(Modus `author`), steht in `/docs/developers/recipes.md`.

## 4 Lokal testen

1. Seite ausliefern, etwa mit `python3 -m http.server 8080` im Ordner der Datei. Ein Server, der jede Datei mit
   `X-Frame-Options` versieht, passt nicht.
2. Eintrag wie in Abschnitt 2 mit Start- und Rücksprungadresse `http://localhost:8080/`. Browser behandeln
   `http://localhost` als sichere Herkunft, darum lädt die Seite auch im Rahmen einer `https://`-Seite.
3. Ein Medium bauen: **Neues Medium → Lernwerkzeug** (oder in einem beliebigen Medium den Baustein
   „Lernwerkzeug“ einfügen), das Werkzeug wählen, Titel eintragen. Die Aufgabe (`task`) schreibt das Werkzeug im
   Modus `author`; für diesen Test reicht der Titel.
4. Das Medium der eigenen Klasse zuweisen.
5. Testen:
   - als Lehrer:in in der Klasse (sie macht dort mit wie eine Schüler:in, `me.role` ist `teacher`), oder
   - als Schüler:in: in einem zweiten Browserprofil über den Klassencode bzw. die Anmeldekarte anmelden und das
     Medium öffnen.
6. Prüfen: Name im Kopf (`Angemeldet als …`), Text schreiben, **Zwischenstand speichern**, Seite neu laden (der
   Text ist wieder da), **Abgeben**. Die Lehrer:in sieht die Abgabe in der Auswertung der Zuweisung.

Fehlerbilder:

| Zeigt | Ursache |
|---|---|
| leerer Rahmen | die Seite verbietet das Einrahmen (`X-Frame-Options`, `frame-ancestors`) |
| `401 invalid_client` beim Anmelden, kein Rücksprung | `redirect_uri` steht nicht genau so am Eintrag |
| CORS-Fehler in der Konsole | die Seite läuft nicht auf der Origin der Start-Adresse (anderer Port, `127.0.0.1` statt `localhost`) |
| `Bitte das Werkzeug aus Stundentakt heraus öffnen.` | Seite direkt aufgerufen, ohne Start-Parameter |
| `Fehler: forbidden` | die Person nimmt an dieser Zuweisung nicht teil |
| `Fehler: not_found` | der Baustein gehört zu einem anderen Werkzeug-Eintrag |

## 5 Wie es weitergeht

- Eigene Daten der Person, Ereignisse, Autorenmodus, Konflikte, Abmelden: `/docs/developers/recipes.md`.
- Alle Felder, Fehlercodes und Grenzen: `/docs/developers/reference.md` bzw. `/api/v1/tools/openapi.json`.
