Beispiel: !node-k ping (Custom Matrix-Bot-Command)

Kleines Referenz-Skript zum Testen des Mitglieds-Antrags / Admin-Freigabe / Sandbox-Flows.

Programmierhandbuch (vollständig): docs/matrix-bot-command-programming.md
API-Kurzreferenz in diesem Ordner: API.md

Verhalten

Eingabe in Matrix	Effekt
!node-k ping	Reaktion 🏓 (Tischtennisschläger) auf die Command-Nachricht
!node-k ping text	Bot antwortet pong
!node-k ping full	Reaktion 🏓 und Antwort pong

Kurzformen !ping, /ping usw. funktionieren ebenfalls, sobald der Befehl im Raum freigegeben ist.

Der eingebaute ping im Backend ist entfernt — nach Freigabe läuft nur noch dieses Skript.

Eigenes Git-Repo anlegen

1. Ordnerinhalt in ein öffentliches HTTPS-Repo kopieren (nur index.js + optional package.json).
2. Commit pushen und den vollen Commit-SHA notieren.
3. In der App: Mein Profil → Matrix → Meine Matrix-Befehle → Neuer Antrag
   • Git-URL: https://github.com/dein-user/matrix-bot-command-ping.git
   • SHA: z. B. a1b2c3d…
   • Verb: ping
   • Räume: Testraum(e), in denen der Bot aktiv ist
   • Entry-Pfad: index.js (Standard)
   • Keine PII-Felder / Fetch-Hosts nötig
4. IT-Admin genehmigt unter Admin → Matrix-Bot-Befehle.

Was du im Code nutzen kannst

Siehe docs/matrix-bot-command-programming.md für:

• alle Handler (onCommand, onSchedule, onWebhook)
• reply, react, fetch
• sender, members, replyTo, PII-Felder
• Cron, Webhook, Limits und Antrags-Workflow

Dieses Ping-Skript zeigt minimal reply und react mit eventId.

Lokal testen (Bundle)

Optional vor dem Antrag das Bundle prüfen — im Monorepo mit laufendem Sidecar:

cd matrix-bot-runtime && npm install
# Quellordner als sourceDir, Entry index.js
curl -s -X POST http://localhost:3011/bundle \
  -H "Authorization: Bearer $MATRIX_BOT_RUNTIME_INTERNAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"sourceDir\":\"$(pwd)/../examples/matrix-bot-command-ping\",\"entryPath\":\"index.js\"}"

Ausführung testen (Bundle-Base64 aus /bundle-Antwort):

curl -s -X POST http://localhost:3011/execute \
  -H "Authorization: Bearer $MATRIX_BOT_RUNTIME_INTERNAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "bundleBase64": "<aus /bundle>",
    "handler": "onCommand",
    "context": { "verb": "ping", "args": "text", "eventId": "$test" },
    "allowedHosts": []
  }'

Erwartung: { "replies": [{ "body": "pong", … }], "reactions": [] }