Bots und Manifest

Wie Bots funktionieren

• Du legst einen Bot im Kundenbereich unter Entwickler an. Pro Konto sind höchstens 10 Bots möglich.
• Der Bot bekommt ein eigenes Token mit dem Präfix zhb_.
• Der Besitzer eines Servers installiert den Bot im Reiter „Bots“ dieses Servers und stimmt den Rechten zu. Mitbenutzer können keine Bots installieren.
• Der Bot läuft bei dir oder auf einem eigenen Zenit-Server. Zenit führt keinen Bot-Code für dich aus.

Manifest

Das Manifest legt fest, was der Bot höchstens darf und wofür er sich interessiert.

Verkleinerst du das Manifest, kürzen sich bestehende Installationen entsprechend. Erweiterst du es, erweitert sich keine Installation von selbst.

Installation pro Server

Eine Installation verbindet einen Bot mit einem Server. Sie hält fest, welche Rechte (grantedScopes) und Ereignisse (eventTypes) der Besitzer erteilt hat, und ihren Status: active oder suspended. Der Besitzer kann die Rechte einer Installation später nur verringern, nicht erhöhen. Einen Bot installierst du auf einem Server nur einmal, ein zweiter Versuch antwortet mit 409 BOT_ALREADY_INSTALLED.

Mit dem Token des Bots listet GET /installations alle Installationen. Ein Zugriffstoken bekommt hier 403 FORBIDDEN.

# ZENIT_TOKEN ist hier das Token des Bots (zhb_…)
curl "https://api.zenit-hosting.de/api/developer/v1/installations?limit=25" \
  -H "Authorization: Bearer $ZENIT_TOKEN"

Wirksame Rechte

Bei jedem Aufruf eines Bots gilt die Schnittmenge aus drei Mengen:

1. den Rechten des Bots,
2. den Rechten seiner Installation auf diesem Server,
3. den aktuellen Rechten des Users, der den Bot installiert hat.

Hat der Bot servers:read und servers:power, die Installation aber nur servers:read, antwortet ein Start-Aufruf mit 403 INSUFFICIENT_SCOPE. Verliert der Installierende seine Freigabe auf dem Server, verliert der Bot sie dort ebenfalls. Die Rechte im Einzelnen stehen unter Rechte.

Deaktivierter und gesperrter Bot

Ein Bot ist active, disabled (du hast ihn deaktiviert) oder suspended (er ist gesperrt). Ist er nicht aktiv, bekommt sein Token auf der Developer-API 401 TOKEN_INVALID, und Zenit stellt keine Ereignisse zu. 409 BOT_NOT_ACTIVE betrifft dagegen die Verwaltung im Kundenbereich, etwa das Installieren eines nicht aktiven Bots.

Bot-Token und Erneuerung

• Beim Anlegen des Bots gibt es noch kein Token. Das erste Token erstellst du unter „Zugangsdaten“ des Bots. Es erscheint dort und bei jeder Erneuerung genau einmal und verlangt deinen zweiten Faktor. Kopiere es sofort.
• Ein Bot-Token läuft nicht ab.
• Eine Erneuerung erzeugt ein neues Token. Das alte Token gilt noch 24 Stunden, die Antwort nennt den Zeitpunkt in previousTokenValidUntil. Tausche das Token in deinem Bot in dieser Zeit aus.
• Das Webhook-Secret ist ein eigenes Geheimnis und wird getrennt erneuert, siehe Webhooks prüfen.

Ereignisse abrufen

Ohne Webhook holt dein Bot Ereignisse mit GET /events?after= ab. Das geht nur mit einem Bot-Token. Die Antwort ist { data, nextCursor }. nextCursor ist die Position nach dem zuletzt gelesenen Ereignis. Reiche ihn beim nächsten Aufruf als after zurück, damit du nur neue Ereignisse bekommst. Ist data leer, bist du auf dem neuesten Stand: Warte kurz und frage erneut. Ohne aktiven Webhook liefert der Feed nur server.activity. Die Installationen deines Bots liest du mit GET /installations. Was nextCursor im Feed von anderen Listen unterscheidet, steht unter Pagination. Zenit bewahrt Ereignisse 14 Tage auf, hole sie vorher ab. Die Ereignistypen und ihre Payloads stehen unter Webhooks prüfen.

const BASE = 'https://api.zenit-hosting.de/api/developer/v1';

// Den letzten Cursor speicherst du dauerhaft, damit ein Neustart nichts doppelt oder gar nicht abholt.
let after = null;

async function pollEvents() {
  const url = new URL(BASE + '/events');
  url.searchParams.set('limit', '100');
  if (after) url.searchParams.set('after', after);

  // ZENIT_TOKEN ist hier das Token des Bots (zhb_…)
  const response = await fetch(url, {
    headers: { Authorization: 'Bearer ' + process.env.ZENIT_TOKEN },
  });
  if (!response.ok) throw new Error('HTTP ' + response.status);

  const page = await response.json();
  for (const event of page.data) {
    handleEvent(event); // nach event.id deduplizieren
  }

  // Im Feed ist nextCursor die Position nach dem zuletzt gelesenen Ereignis. Immer speichern, wenn er nicht null ist.
  if (page.nextCursor) after = page.nextCursor;

  return page.data.length;
}

async function run() {
  while (true) {
    const count = await pollEvents();
    // Leere data heißt: aufgeholt. Kurz warten und mit demselben Cursor erneut fragen.
    if (count === 0) await new Promise((resolve) => setTimeout(resolve, 5000));
  }
}

Beispiel: Zenit Git

„Zenit Git“ (Kennung zenit-git) ist ein Bot von Zenit selbst. Er zeigt, wie ein Bot aufgebaut ist:

• Sein Manifest nennt die Rechte git:read, git:deploy, git:manage, servers:power und servers:console sowie das Ereignis server.activity.
• Er gilt als installiert, sobald ein Server eine Git-Quelle hat. Du musst ihn nicht installieren. Im Reiter „Bots“ des Servers steht er als eigene Zeile, und „Verwalten“ führt zum Deploy-Bereich des Servers.
• Über die API liest du die Git-Quellen eines Servers, löst Deploys aus und fragst Deployments ab. Dafür brauchst du git:read und git:deploy und, als Mitbenutzer, die Freigaben canViewServer und canDeployGit.
• Ein Deploy hat den Auslöser api. Ist das Paket des Servers nicht für Git-Deployments freigegeben, antwortet die API mit 409 GIT_DEPLOY_NOT_ALLOWED.

# Git-Quellen des Servers lesen (Recht git:read)
curl "https://api.zenit-hosting.de/api/developer/v1/servers/$SERVER_ID/git/sources" \
  -H "Authorization: Bearer $ZENIT_TOKEN"

# Deploy auslösen (Recht git:deploy); sha ist optional, 7 bis 64 Hexzeichen
curl -X POST "https://api.zenit-hosting.de/api/developer/v1/servers/$SERVER_ID/git/sources/$SOURCE_ID/deploy" \
  -H "Authorization: Bearer $ZENIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"sha": "3f9c2ab"}'

Die Endpunkte GET /servers/{id}/git/deployments und GET /servers/{id}/git/deployments/{deploymentId} liefern den Stand eines Deployments. Alle Felder stehen in der API-Referenz.