Channel-Integrations-Verträge

Das ist eine Entwickler-Referenz. Endnutzer-Channel- Dokumentation beginnt unter Wie Channels funktionieren; diese Seite ist für Ingenieure, die in functions/src/channels/ arbeiten.

Jede Integration implementiert das Basis-Integration-Interface plus null oder mehr Capability-Interfaces. Der Dispatcher hängt nur von diesen Interfaces ab, nie von konkreten Klassen.

Quelle der Wahrheit: functions/src/channels/contracts/Integration.ts.

Basis-Interface

interface Integration {
  readonly metadata: IntegrationMetadata;
  healthCheck(connection: ConnectionRecord): Promise<HealthStatus>;
}

IntegrationMetadata beschreibt die Integration für den UI-Katalog:

interface IntegrationMetadata {
  id: string;              // e.g. "linkedin", "slack-webhook"
  name: string;            // Display name
  category: IntegrationCategory;  // "notify" | "social" | "email" | "seo" | "ads" | "crm"
  sku: IntegrationSku;     // "free" | "channels" | "growth"
  capabilities: IntegrationCapability[];  // ["adapt", "publish"] or ["notify"]
  authType: IntegrationAuthType;  // "oauth2" | "webhook" | "apikey" | "none"
  iconUrl: string;
}

Capability-Interfaces

NotifiableIntegration

Fire-and-forget-Benachrichtigungen. Genutzt von Slack, Discord, IndexNow, E-Mail, Telegram, WhatsApp.

interface NotifiableIntegration extends Integration {
  notify(ctx: NotifyContext): Promise<NotifyResult>;
}

NotifyContext trägt den Beitragstitel, die URL, den Veröffentlichungs-Status ("published" oder "awaiting_review"), die Bearbeitungs-URL, das Locale, das pro-Verbindung-Locale-Override und die entschlüsselten Geheimnisse. Die Integration formatiert eine Nachricht und sendet sie.

NotifyResult meldet "ok", "transient_error" oder "permanent_error" — der Dispatcher nutzt das für Wiederholungs-Entscheidungen.

OAuthIntegration

Vollständiger OAuth-2.0-Lebenszyklus. Genutzt von LinkedIn (und künftig Mailchimp, X).

interface OAuthIntegration extends Integration {
  buildAuthorizeUrl(state: string, redirectUri: string): string;
  handleCallback(ctx: OAuthCallbackContext): Promise<OAuthTokens>;
  refreshTokens(tokens: OAuthTokens): Promise<OAuthTokens>;
  revoke(tokens: OAuthTokens): Promise<void>;
}

Der OAuth-Flow besteht aus zwei Cloud-Funktionen:

1. channelsOAuthInit stellt ein signiertes State-JWT aus, ruft buildAuthorizeUrl() auf, gibt die URL zurück.
2. channelsOAuthCallback empfängt den Redirect, verifiziert den State, ruft handleCallback() auf, verschlüsselt Tokens, persistiert die Verbindung, leitet zu wp-admin weiter.

OAuthTokens trägt accessToken, optional refreshToken, optional expiresAt, scope und anbieterspezifische extras (z. B. LinkedIns Person-URN).

AdaptableIntegration

KI-gestütztes Inhaltsumschreiben. Genutzt von LinkedIn (und künftig Mailchimp).

interface AdaptableIntegration extends Integration {
  adapt(ctx: AdaptContext): Promise<AdaptedContent>;
}

AdaptContext liefert den vollständigen Beitrags-Snapshot (AdaptablePost) mit Titel, Body-Text, Auszug, Persona, Keywords und Locale. Die adapt()-Methode der Integration delegiert an eine injizierte KI-Funktion, die eine channel-spezifische Prompt-Vorlage nutzt.

AdaptedContent gibt die integrationsspezifische Payload (z. B. { text } für LinkedIn), Token-Verbrauchsstatistiken und die verwendete Modell-ID zurück.

PublishableIntegration

Postet Inhalte an eine Drittanbieter-API. Genutzt von LinkedIn (und künftig Mailchimp, X).

interface PublishableIntegration extends Integration {
  publish(ctx: PublishContext): Promise<PublishResult>;
}

PublishContext enthält entschlüsselte Tokens, den adaptierten Inhalt (Ausgabe von adapt()), den Verbindungsdatensatz und den Beitrags-Snapshot.

PublishResult meldet Status ("ok", "transient_error", "auth_expired", "permanent_error"), optional externalRef (Beitrags-ID des Anbieters) und optional externalUrl (Link zum veröffentlichten Artefakt).

WebhookIntegration

Konfiguriert über eine vom Nutzer eingefügte Webhook-URL. Genutzt von Slack und Discord.

interface WebhookIntegration extends Integration {
  validateTarget(url: string): Promise<void>;
}

Validiert die URL-Form und pingt sie optional, bevor gespeichert wird. Der Endpunkt channelsSaveWebhookConnection ruft das auf, bevor die URL verschlüsselt wird.

Type Guards

Der Dispatcher nutzt Type Guards (nicht instanceof), um Capabilities zu prüfen:

isOAuthIntegration(i)      // authType === "oauth2"
isAdaptableIntegration(i)  // capabilities includes "adapt"
isPublishableIntegration(i) // capabilities includes "publish"
isWebhookIntegration(i)    // authType === "webhook"
isNotifiableIntegration(i) // capabilities includes "notify"

Aktuelle Integrations-Matrix