# Rezepte

Fertige Ausschnitte für häufige Aufgaben eines Lernwerkzeugs. Sie setzen die Seite aus `/docs/developers/quickstart.md` voraus,
vor allem diese Teile:

- `STUNDENTAKT` – die Adresse der Instanz, z. B. `https://stundentakt.eu`.
- `launch` – die gemerkten Start-Parameter (`mode`, `assignment`, `block`, `document`, `response`, `lang`).
- `api(method, path, body)` – ruft `STUNDENTAKT + '/api/v1/tools' + path` mit dem Zugriffstoken auf, erneuert bei
  `token_expired`, meldet bei `token_revoked`/`token_invalid` still neu an, wartet bei `too_many_requests` und
  `maintenance` `Retry-After` Sekunden. Es gibt das JSON zurück (bei `204` `null`) und wirft sonst einen Fehler
  mit `reason`, `status` und dem ganzen Körper in `body`.

Alle Felder und Grenzen stehen in `/docs/developers/reference.md`.

## Eigene Programme speichern und teilen (Records)

Was einer Person gehört und an keiner Aufgabe hängt – eigene Programme, Vokabellisten, Einstellungen – ist ein
**Record**. Die Datenart (`collection`) benennt das Werkzeug selbst (`[a-z0-9_-]`, 1–64 Zeichen); `data` ist
beliebiges JSON bis 64 KB, `schema` die eigene Formatnummer.

```js
// Anlegen: privat, solange die Person nichts anderes wählt.
const program = await api('POST', '/collections/programs/records', {
  data: { name: 'Ampel', code: 'rot(); warte(2); gruen();' },
  schema: 1,
});

// Die eigenen, zuletzt geänderte zuerst (Seiten zu höchstens 100).
const mine = await api('GET', '/collections/programs/records?sort=-updated&per_page=50&page=1');
// → { items: [ { id, collection, data, schema, visibility, created_at, updated_at, owner }, … ], page, per_page, total }

// Ändern: updated_at so mitschicken, wie zuletzt gelesen (sonst 409, siehe „Konflikte“).
const renamed = await api('PATCH', '/collections/programs/records/' + program.id, {
  data: { ...program.data, name: 'Ampel 2' },
  updated_at: program.updated_at,
});

// Teilen: group = wer mit ihr eine aktive Klasse teilt, team = ihre Schule, public = jede:r mit der ULID.
const shared = await api('PATCH', '/collections/programs/records/' + program.id, {
  visibility: 'group',
  updated_at: renamed.updated_at,
});

// Was andere mit der Person teilen (nur lesen; owner.alias ist Pseudonym bzw. Anzeigename).
const fromOthers = await api('GET', '/collections/programs/records?scope=shared');

// Löschen.
await api('DELETE', '/collections/programs/records/' + program.id);
```

Ein öffentlicher Record (`visibility: 'public'`) lässt sich ohne Token lesen, etwa für einen Teilen-Link des
Werkzeugs. Die Antwort trägt CORS-Kopfzeilen nur für die Origin des Werkzeugs; eine fremde Seite liest ihn über
ihren eigenen Server.

```js
const response = await fetch(STUNDENTAKT + '/api/v1/tools/records/' + id, { credentials: 'omit' });
const record = response.ok ? await response.json() : null; // 404 für alles, was nicht öffentlich ist
```

Speicher: `GET me` nennt unter `entitlements.records` die Grenze des Teams (`limit_bytes`), den eigenen Verbrauch
(`own_bytes`) und die Grenze je Record (`record_max_bytes`). Ist das Team voll, antwortet das Schreiben
`413 quota_exceeded`; eine Schüler:in ohne aktive Klasse hat keinen Speicher (`403 no_storage`).

## Fortschritt melden (Ereignisse)

Ereignisse folgen der Form einer xAPI-Aussage (Person, Verb, Objekt, Ergebnis, Zeit); Person und Werkzeug nimmt
Stundentakt immer aus dem Token. Bis zu 100 je Aufruf, ganz oder gar nicht gespeichert, Antwort `201 {recorded}`.

**Im Unterricht** (es gibt `launch.assignment`): Mit `block` zählen sie in der Auswertung der Klasse
(„Vom Werkzeug gemeldet“: je Verb und Code „x von y“ Schüler:innen, bei `run` die Läufe vor der Abgabe).

```js
await api('POST', '/assignments/' + launch.assignment + '/events', {
  events: [
    { block: launch.block, verb: 'run', result: { success: false, duration: 'PT2.5S' } },
    { block: launch.block, verb: 'error', code: 'err.syntax.indent' },
    { block: launch.block, verb: 'step', result: { success: true, score: 0.5 } },
    { block: launch.block, verb: 'submit', result: { success: true, score: { raw: 8, min: 0, max: 10 } } },
  ],
});
```

**Ohne Unterricht** (das Werkzeug wird frei benutzt): kein `block`; als Objekt nur ein eigener Record.

```js
await api('POST', '/events', {
  events: [{ verb: 'step', object: { type: 'record', id: program.id }, result: { success: true, duration: 4200 } }],
});
```

Empfohlene Verben: `run` (ausgeführt), `error` (mit `code`), `step` (Schritt geschafft), `submit` (abgegeben),
`reset` (neu begonnen); andere Wörter bis 40 Zeichen sind erlaubt. `result.score` ist eine Zahl von 0 bis 1 oder
`{raw, min, max, scaled}`, `duration` eine ISO-8601-Dauer oder Millisekunden. Offline gesammelte Ereignisse mit
`timestamp` (ISO 8601 mit Zone) binnen 24 Stunden nachreichen; ältere Zeiten setzt Stundentakt auf „vor 24 Stunden“.

```js
// Puffern und gebündelt senden.
const queue = [];
const track = (event) => queue.push({ ...event, timestamp: new Date().toISOString() });
async function flush() {
  while (queue.length) {
    const batch = queue.slice(0, 100);
    await api('POST', '/assignments/' + launch.assignment + '/events', { events: batch });
    queue.splice(0, batch.length);
  }
}
setInterval(() => flush().catch(() => {}), 10000);
```

## Autorenmodus mit Entwurf

Im Modus `author` (Start mit `?mode=author&document=…&block=…`) schreibt die Lehrer:in die Aufgabe im Werkzeug.
`PUT blocks/{block}` ist **veröffentlichen**: Die Klasse sieht die Änderung sofort. Stundentakt hat bewusst keinen
eigenen Entwurfsplatz je Baustein; einen Entwurf, den nur die Autorin sieht, hält das Werkzeug als privaten
Record (hier Datenart `drafts`) und veröffentlicht ihn auf Knopfdruck.

```js
// Aufgabe lesen: blocks enthält die Bausteine dieses Werkzeugs im Medium, mit hidden für die Autorin.
const { document: medium, blocks } = await api('GET', '/documents/' + launch.document);
const block = blocks.find((b) => b.ulid === launch.block);
// block = { ulid, type: 'tool', payload: { tool, title, task }, updated_at, hidden }

// Eigenen Entwurf zu diesem Baustein suchen.
const list = await api('GET', '/collections/drafts/records?per_page=100');
let draft = list.items.find((record) => record.data.block === block.ulid) ?? null;

// Beim Tippen speichern (privat, unsichtbar für die Klasse).
async function saveDraft(title, task, hidden) {
  const data = { block: block.ulid, based_on: draft?.data.based_on ?? block.updated_at, title, task, hidden };
  draft = draft
    ? await api('PATCH', '/collections/drafts/records/' + draft.id, { data, updated_at: draft.updated_at })
    : await api('POST', '/collections/drafts/records', { data });
}

// Veröffentlichen: nur, wenn die Aufgabe seit based_on niemand geändert hat.
async function publish() {
  const { title, task, hidden, based_on } = draft.data;
  try {
    const result = await api('PUT', '/blocks/' + block.ulid, { title, task, hidden, updated_at: based_on });
    await api('DELETE', '/collections/drafts/records/' + draft.id);
    draft = null;
    Object.assign(block, result.block);
    return result; // { complete, incomplete, block }
  } catch (error) {
    if (error.reason !== 'conflict') throw error;
    // Jemand hat die Aufgabe inzwischen geändert: error.body.block ist der aktuelle Stand.
    // Zusammenführen oder der Autorin beide Fassungen zeigen, dann mit dessen updated_at erneut veröffentlichen.
    return { conflict: error.body.block };
  }
}
```

- Was der Körper von `PUT blocks/{block}` weglässt, bleibt; `task` und `hidden` je höchstens 64 KB.
- `complete: false` nimmt den ganzen Baustein aus dem Unterricht, bis er fertig ist (die Klasse sieht ihn nicht);
  das ist kein Entwurf neben einer veröffentlichten Fassung.
- `hidden` (Tests, Musterlösung) sieht nur, wer den Baustein ändern darf, und das Werkzeug in ihrer Hand.

## Konflikte (409)

Zwei Stellen schützen vor stillem Überschreiben, beide mit `updated_at` als Vorbedingung:

| Route | `updated_at` | Vergleich | aktueller Stand in |
|---|---|---|---|
| `PUT blocks/{block}` | freiwillig (ohne: der letzte Aufruf gewinnt) | auf die Sekunde | `body.block` |
| `PATCH collections/{c}/records/{id}` | Pflicht | auf die Mikrosekunde | `body.record` |

```js
async function patchRecord(collection, record, change, merge) {
  try {
    return await api('PATCH', `/collections/${collection}/records/${record.id}`, { ...change, updated_at: record.updated_at });
  } catch (error) {
    if (error.reason !== 'conflict') throw error;
    const current = error.body.record;
    return patchRecord(collection, current, merge(current, change), merge);
  }
}
```

## Abmelden

```js
async function signOut() {
  await api('POST', '/logout');            // widerruft die Tokens der Person in allen Werkzeugen
  sessionStorage.removeItem('tokens');
  // Im eigenen Fenster auf Wunsch auch aus Stundentakt abmelden; next muss eine eingetragene Rücksprungadresse sein.
  if (window.parent === window) {
    location.href = STUNDENTAKT + '/logout?next=' + encodeURIComponent(REDIRECT_URI);
  }
}
```

Meldet sich die Person in Stundentakt ab (oder eine andere im selben Browser an), erfährt das Werkzeug es beim
nächsten Aufruf als `token_revoked`.

## Fehler behandeln

Jeder Fehler ist `{message, reason}`; entschieden wird nach `reason`, nie nach `message`.

| `reason` | Status | Reaktion des Werkzeugs |
|---|---|---|
| `token_expired` | 401 | mit dem Erneuerungstoken erneuern, Aufruf wiederholen |
| `token_revoked`, `token_invalid` | 401 | still neu anmelden (`prompt=none`); kommt `login_required`, Anmelden anbieten |
| `wrong_scope` | 403 | mit `tools:write` anmelden |
| `wrong_origin` | 403 | Seite läuft nicht auf der Origin der Startadresse: Eintrag prüfen |
| `tool_unavailable` | 403 | Eintrag gesperrt oder gelöscht: Hinweis zeigen, nichts mehr senden |
| `forbidden` | 403 | die Person darf das nicht: Hinweis zeigen |
| `guest_not_supported` | 403 | Gast: nur lokal speichern |
| `no_storage` | 403 | Schüler:in ohne Klasse: Records lokal halten |
| `not_found` | 404 | Adresse oder ULID falsch, oder nicht dieses Werkzeugs |
| `withdrawn` | 404 | die Antwort einer Durchsicht gibt es nicht mehr |
| `conflict` | 409 | aktuellen Stand aus `block` bzw. `record` übernehmen oder zusammenführen |
| `too_large`, `quota_exceeded` | 413 | weniger speichern bzw. Hinweis auf den Speicher |
| `invalid` | 422 | Felder in `errors` |
| `not_open` | 422 | `detail`: `not_yet`, `closed` oder `wrong_mode`; Eingabe sperren, Hinweis zeigen |
| `too_many_requests` | 429 | `Retry-After` Sekunden warten |
| `maintenance` | 503 | `Retry-After` Sekunden warten, dann erneut versuchen |

```js
function explain(error) {
  switch (error.reason) {
    case 'not_open':
      return { not_yet: 'Die Aufgabe ist noch nicht offen.', closed: 'Die Abgabe ist geschlossen.',
               wrong_mode: 'Die Aufgabe ist gerade nur zum Ansehen.' }[error.body.detail];
    case 'tool_unavailable': return 'Dieses Werkzeug ist in Stundentakt gesperrt.';
    case 'forbidden': return 'Das ist hier nicht erlaubt.';
    case 'quota_exceeded': return 'Der Speicher ist voll.';
    default: return error.message;
  }
}
```

## Rahmen oder eigenes Fenster

| | im Rahmen (`inline`) | im eigenen Fenster (`full`) |
|---|---|---|
| Start | Stundentakt rahmt die Startadresse ein | Stundentakt öffnet die Startadresse in einem neuen Tab |
| still anmelden | der Rahmen navigiert zu `/oauth/authorize?…&prompt=none`; fehlt dem Browser das Cookie, ruft Stundentakt die Adresse einmal selbst erneut auf, das Werkzeug merkt nichts | das Fenster navigiert zu `/oauth/authorize?…&prompt=none` |
| niemand angemeldet | `error=login_required`: Anmeldung in einem neuen Fenster öffnen (ohne `prompt`), danach im Rahmen erneut still | dieselbe Adresse ohne `prompt` führt über die Anmeldeseite und zurück |
| Höhe | per `postMessage` melden (`type: 'height'`) | entfällt |
| Neu laden | Tokens aus `sessionStorage`, sonst still neu | ebenso |

Tokens reisen nie per `postMessage` und nie in einer Adresse; jede Seite des Werkzeugs holt sich ihre eigenen.

## Meine Kurse

Ohne Start aus Stundentakt (Lesezeichen, eigene Startseite des Werkzeugs) zeigt das Werkzeug, woran die Person
mit ihm arbeitet: `GET me/assignments` nennt ihre Zuweisungen mit Bausteinen **dieses** Werkzeugs, nach Frist
sortiert (ohne Frist zuletzt, dann die neueste), und Kurse, deren Stunden auf solche Medien verweisen. Die Klasse
kommt nur mit ihrem Namen.

In die Seite aus `/docs/developers/quickstart.md` gehört dafür eine Liste und ein Formular für den nächsten Abschnitt:

```html
<ul id="courses"></ul>
<form id="link-form" hidden>
  <input name="link" placeholder="Link oder Code aus Stundentakt" required>
  <button>Öffnen</button>
</form>
```

Im Ablauf ersetzt das Werkzeug Schritt b) („ohne Start-Parameter“) durch die Liste:

```js
// b) ohne Start-Parameter: anmelden und zeigen, was die Person mit diesem Werkzeug zu tun hat
if (!launch) {
  if (!tokens()) return signInSilently();
  $('link-form').hidden = false;
  return showCourses();
}
```

```js
// Alle Seiten holen (je höchstens 100).
async function myAssignments() {
  const items = [];
  for (let page = 1; ; page++) {
    const result = await api('GET', '/me/assignments?per_page=100&page=' + page);
    items.push(...result.items);
    if (items.length >= result.total || result.items.length === 0) return items;
  }
}

async function showCourses() {
  const list = $('courses');
  list.replaceChildren();
  for (const entry of await myAssignments()) {
    // entry = { assignment, role, document: {ulid, name, type}, group: {name} | null, mode, open_from, closes_at,
    //           open, progress: {done, total, blocks} | null, last_activity, blocks: [ulid], lessons? }
    const item = document.createElement('li');
    const due = entry.closes_at ? ' · bis ' + new Date(entry.closes_at).toLocaleDateString(lang) : '';
    // Bei einem Kurs ist progress schon über seine Medien summiert.
    const done = entry.progress ? ` · ${entry.progress.done} von ${entry.progress.total} abgegeben` : '';
    const last = entry.last_activity ? ' · zuletzt ' + new Date(entry.last_activity).toLocaleDateString(lang) : '';
    item.append(`${entry.document.name} (${entry.group?.name ?? 'Link'})${due}${done}${last} `);

    // Jeder Baustein startet das Werkzeug wie ein Start aus Stundentakt im Modus learn.
    for (const block of entry.blocks) item.append(openButton('Öffnen', entry.assignment, block));

    // Ein Kurs bringt seine Stunden mit den Medien mit, die dieses Werkzeug enthalten.
    for (const lesson of entry.lessons ?? []) {
      for (const medium of lesson.media) {
        // Ohne Zuweisung an die Klasse (assignment: null) erreicht die Person das Medium nur über seinen Link.
        if (!medium.assignment) continue;
        for (const block of medium.blocks) {
          item.append(openButton(`${lesson.topic ?? 'Stunde'}: ${medium.name}`, medium.assignment, block));
        }
      }
    }
    list.append(item);
  }
  if (!list.children.length) status('Noch keine Aufgabe mit diesem Werkzeug.');
}

// Dieselbe Adresse, die ein Start aus Stundentakt öffnet; danach läuft alles wie im Schnellstart.
function openTask(assignment, block) {
  location.href = REDIRECT_URI + '?' + new URLSearchParams({ mode: 'learn', assignment, block, lang });
}

function openButton(text, assignment, block) {
  const button = document.createElement('button');
  button.textContent = text;
  button.onclick = () => openTask(assignment, block);
  return button;
}
```

- `role: 'teacher'`: die Lehrer:in der Klasse. `progress` und `last_activity` sind dann `null`; die Klasse wertet
  sie in Stundentakt aus.
- `last_activity`: wann die Person hier zuletzt abgegeben, einen Zwischenstand gespeichert oder dieses Werkzeug ein
  Ereignis gemeldet hat; bei einem Kurs auch in seinen Medien. `null`, solange nichts davon geschah.
- Ein Menüpunkt „Profil bei Stundentakt“ öffnet `profile_url` aus `GET me` in einem neuen Tab.
- `open: false` heißt: noch nicht offen, Frist vorbei oder „Nur ansehen“. Genaueres nennt `GET assignments/{a}`
  (`window.phase`), eine Abgabe antwortet dann `422 not_open`.
- Links geteilter Medien erscheinen erst, wenn die Person dort abgegeben oder einen Zwischenstand gespeichert hat.

## Kurs per Stundentakt-Link öffnen

Eine Schüler:in kopiert die Adresse aus Stundentakt (`https://stundentakt.eu/m/…`, `/d/…`, einen Kurzlink oder nur
den Code von der Tafel, `ABC-DEF`) und fügt sie im Werkzeug ein. `GET links/resolve` löst sie auf, wie die App es
täte, und antwortet mit derselben Form wie ein Eintrag aus „Meine Kurse“.

```js
async function openPasted(text) {
  try {
    const entry = await api('GET', '/links/resolve?url=' + encodeURIComponent(text.trim()));
    // { assignment, role, document, group, mode, open_from, closes_at, open, progress, blocks, lessons? }
    if (entry.blocks.length === 1 && !entry.lessons) return openTask(entry.assignment, entry.blocks[0]);

    // Mehrere Aufgaben dieses Werkzeugs im Medium oder ein Kurs: wählen lassen.
    const list = $('courses');
    list.replaceChildren();
    for (const block of entry.blocks) list.append(openButton(entry.document.name, entry.assignment, block));
    for (const lesson of entry.lessons ?? []) {
      for (const medium of lesson.media.filter((m) => m.assignment)) {
        for (const block of medium.blocks) list.append(openButton(medium.name, medium.assignment, block));
      }
    }
  } catch (error) {
    // Fremde Adresse, ein Medium ohne dieses Werkzeug, eine Klasse, in der sie nicht ist: alles dieselbe Antwort.
    if (error.reason === 'not_found') return status('Unter diesem Link gibt es hier nichts zu tun.');
    if (error.reason === 'invalid') return status('Bitte einen Link einfügen.');
    throw error;
  }
}

$('link-form').onsubmit = (event) => {
  event.preventDefault();
  openPasted(new FormData(event.target).get('link'));
};
```

- Ein Medium führt in die Klasse der Person, die es hat; sonst auf den Link eines geteilten Mediums, das Teilnahme
  annimmt (`role: 'guest'`). Die Zuweisung des Links legt Stundentakt beim ersten Mal an, wie beim Öffnen in der App.
- Ein **Klassencode** nennt kein Medium (`404`): dafür ist „Meine Kurse“ da.
- Die Antwort verrät nie, ob es ein Medium gibt, das die Person nicht erreicht. Das Werkzeug sagt bei `404` nur
  „nichts zu tun“.
- Gäste haben kein Token; für sie bleibt nur das Gerät.

## Anzeige je Baustein

Ob das Werkzeug im Rahmen der Seite (`inline`) oder in einem eigenen Fenster (`full`) startet, stellt der Eintrag
ein. Ein Baustein kann es für sich ändern: `payload.display` ist `inline`, `full` oder `null` (wie der Eintrag). Die
Lehrer:in wählt es im Baustein unter „Anzeige“; ein Werkzeug im Autorenmodus kann es mit `PUT blocks/{block}` setzen,
etwa weil eine Aufgabe einen großen Bildschirm braucht.

```js
// Im Autorenmodus: die Aufgabe braucht Platz, also in einem eigenen Fenster.
const { block } = await api('PUT', '/blocks/' + launch.block, { display: 'full' });
// block.payload.display === 'full'

// Zurück zur Einstellung des Eintrags (was der Körper weglässt, bleibt).
await api('PUT', '/blocks/' + launch.block, { display: null });

// Anderes ist 422 invalid mit errors.display.
```

```js
// Beim Start: woran erkennt das Werkzeug, wie es gerade läuft? Am Fenster selbst.
const framed = window.parent !== window;
if (framed) reportHeight(); // nur im Rahmen: Höhe per postMessage melden (quickstart.md)
```

- Start und Darstellung lesen den Wert des Bausteins: Die Medium-Ansicht zeigt einen Baustein mit `full` als Karte,
  die das Werkzeug in einem neuen Tab öffnet, die Bühne ebenso; `/tools/launch/{block}?frame=1` rahmt ihn im Modus
  `learn` nicht ein, sondern öffnet das Werkzeug selbst.
- Der Autorenmodus im Editor bleibt immer ein Rahmen, gleich welche Anzeige.
- `GET documents/{d}` und `GET assignments/{a}` nennen den Wert in `blocks[].payload.display` (`null`: wie der Eintrag).
