zhs-client-js

Kleine Node.js-Library, um ausgewählte ZHS München Sportkurse (z.B. freies Volleyball) zu buchen bzw. in den Warenkorb zu legen.
Die Library nutzt deine bestehenden Login-Cookies und kommuniziert direkt mit der internen GraphQL-API von kurse.zhs-muenchen.de.

⚠️ Inoffizielles Projekt. Keine Verbindung zum ZHS. Nutzung auf eigene Verantwortung.

---

Features

• ✔️ Kurse direkt über die interne GraphQL-API reservieren
  (Add-to-Cart / Reservierung)

• ✔️ Unterstützte Kurse (bisher):
  Volleyball (Slot-basiert)

  • Volleyball – Freies Spiel Montag
  • Volleyball – Freies Spiel Donnerstag
  • Volleyball – Freies Spiel Samstag

  Badminton (Slot-basiert)

  • Badminton – Freies Spiel Donnerstag
  • Badminton – Freies Spiel Freitag
  • Badminton – Freies Spiel Samstag

  Basketball (Slot-basiert)

  • Basketball – Freies Spiel Mittwoch
  • Basketball – Freies Spiel Donnerstag

  Tischtennis (Slot-basiert)

  • Tischtennis – Freies Spiel Samstag

  Nicht slot-basierte Kurse

  • Outdoor-Fitnessanlage – Freies Training
  • Golf – Freies Spiel

• ✔️ Wochenslot-Kurse automatisch berechnen
  → nächster Termin + optionalem Wochenoffset
  (z.B. übernächster Donnerstag)

• ✔️ Flexible Authentifizierung über Cookies
  (JSON-Datei, Objekt oder fertiger Cookie-Header)

• ⛔ Checkout (Bezahlung) aktuell nicht implementiert
  (muss manuell im Browser erfolgen)

---

⚠️ Hinweis / Exploit: Volleyball-Kurse unabhängig vom Buchungszeitraum buchen

Die Library erlaubt es, z.B Volleyball-Wochenslotkurse bereits vor dem offiziellen Buchungsstart zu reservieren.

➡️ Dadurch entsteht ein kleiner Exploit, der dir ermöglicht, Volleyball-Slots frühzeitig zu sichern.

⚠️ Nutzung auf eigene Verantwortung

---

Installation

npm install

Das Projekt nutzt ES-Module ("type": "module").
Node.js 18+ wird empfohlen, da hier fetch global verfügbar ist.

Wenn du das Package als Dependency in einem anderen Projekt verwenden willst:

npm install zhs-client-js

---

Cookies vorbereiten

Um Anfragen an die ZHS-API zu authentifizieren, benötigst du deine Login-Cookies.
Im Ordner example/ findest du eine Vorlage: foo.cookies.json.

Beispiel:

{
  "name": "foo",
  "cookie": {
    "acceptedCookies": true,
    "csrf_token_xxx": "...",
    "ory-session": "...",
    "payment": "...",
    "rl_anonymous_id": "...",
    "rl_page_init_referrer": "...",
    "rl_page_init_referring_domain": "...",
    "rl_session": "...",
    "rl_user_id": "..."
  }
}

Wichtig:
Diese Datei enthält deine Session → niemals committen oder teilen!

---

Schnellstart (Beispiel: Volleyball buchen)

Im example-Ordner liegt volleyball.js:

import { ZHSClient } from "../index.js";

const client = ZHSClient.fromCookieFile("./foo.cookies.json");

// Nächsten Donnerstag buchen
const result = await client.book("Volleyball - Freies Spiel Donnerstag");
console.log(result);

// Übernächsten Donnerstag (Offset = 1)
const result2 = await client.book("Volleyball - Freies Spiel Donnerstag", 1);
console.log(result2);

// Checkout muss später manuell im Browser erfolgen

---

API

Import

Alles wird über index.js bereitgestellt:

import {
  ZHSClient,
  courses,
  getNextDayDate,
  offsetWeek
} from "zhs-client-js";

---

ZHSClient

Der zentrale Einstiegspunkt.

Client erstellen

// 1) Aus Cookie-Datei
const client = ZHSClient.fromCookieFile("./foo.cookies.json");

// 2) Aus Cookie-Objekt
const client2 = ZHSClient.fromCookieObject({
  name: "foo",
  cookie: { /* ... */ }
});

// 3) Aus Cookie-Header-String
const client3 = ZHSClient.fromCookieString("ory-session=...; rl_session=...;");

Intern wird das Cookie-Objekt in einen String wie
key=value; key2=value2; ...
umgewandelt.

---

book(courseNameOrId, offset = 0)

Legt den gewünschten Kurs in den Warenkorb.

const result = await client.book("Volleyball - Freies Spiel Samstag");

Parameter:

• courseNameOrId
  Kursname aus courses oder die ZHS-Kurs-ID
  (IDs werden automatisch zugeordnet)

• offset
  Wochenversatz (z.B. 1 = nächste Woche)
  Berechnung über getNextDayDate() + offsetWeek().

Ergebnis:

{
  status: "booked" | "not_booked" | "error",
  response,
  responseBody
}

• "error" → HTTP-Fehler
• "not_booked" → API antwortet ohne data
• "booked" → erfolgreiche Reservierung

---

📌 getCourseSlotDetails(courseName, offset = 0)

Fragt freie Plätze & Buchungsfenster des Kurses ab.

'''js const info = await client.getCourseSlotDetails("Badminton - Freies Spiel Samstag", 1); console.log(info); '''

---

courses

Enthält Mapping aller unterstützten Kurse:

import { courses } from "zhs-client-js";

console.log(Object.keys(courses));

Jeder Kurs besitzt:

• id – interne ZHS-Kurs-ID
• queryString(offset) – erzeugt dynamische GraphQL-Requests

Bei Volleyball basiert der Termin auf dynamischer Wochentagsberechnung.

---

Helper-Funktionen

Aus helper.js:

• generateCookieString(obj) – erzeugt Cookie-Header
• loadJsonFile(path) – lädt JSON synchron
• getNextDayDate(day) – nächsten bestimmten Wochentag bestimmen
• offsetWeekday(day, offset) – Wochentag verschieben
• offsetWeek(date, offset) – Datum um X Wochen verschieben

---

Sicherheit & Verantwortung

• Nutze das Tool nur für dein eigenes Konto.
• Cookies niemals teilen.
• Exploit nicht übertreiben.
• Beachte die Nutzungsbedingungen des ZHS.

---

readme.md erstellt durch ChatGPT5.1