Contrats d’intégration de canal

Ceci est une référence pour développeurs. La documentation des canaux pour utilisateurs finaux commence à Comment fonctionnent les canaux ; cette page est pour les ingénieurs travaillant à l’intérieur de functions/src/channels/.

Chaque intégration implémente l’interface de base Integration plus zéro ou plusieurs interfaces de capacité. Le dispatcher dépend uniquement de ces interfaces, jamais de classes concrètes.

Source de vérité : functions/src/channels/contracts/Integration.ts.

Interface de base

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

IntegrationMetadata décrit l’intégration pour le catalogue UI :

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;
}

Interfaces de capacité

NotifiableIntegration

Notifications fire-and-forget. Utilisé par Slack, Discord, IndexNow, E-mail, Telegram, WhatsApp.

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

NotifyContext porte le titre de l’article, l’URL, le statut de publication ("published" ou "awaiting_review"), l’URL d’édition, la langue, le remplacement de langue par connexion et les secrets déchiffrés. L’intégration met en forme un message et l’envoie.

NotifyResult rapporte "ok", "transient_error" ou "permanent_error" — le dispatcher utilise ceci pour les décisions de réessai.

OAuthIntegration

Cycle de vie OAuth 2.0 complet. Utilisé par LinkedIn (et plus tard 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>;
}

Le flux OAuth est constitué de deux Cloud Functions :

1. channelsOAuthInit émet un JWT de state signé, appelle buildAuthorizeUrl(), renvoie l’URL.
2. channelsOAuthCallback reçoit la redirection, vérifie le state, appelle handleCallback(), chiffre les jetons, persiste la connexion, redirige vers wp-admin.

OAuthTokens porte accessToken, optionnellement refreshToken, optionnellement expiresAt, scope et des extras spécifiques au fournisseur (par ex. l’URN de personne LinkedIn).

AdaptableIntegration

Réécriture de contenu propulsée par IA. Utilisé par LinkedIn (et plus tard Mailchimp).

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

AdaptContext fournit l’instantané complet de l’article (AdaptablePost) avec titre, texte du corps, extrait, persona, mots-clés et langue. La méthode adapt() de l’intégration délègue à une fonction d’IA injectée qui utilise un modèle de prompt spécifique au canal.

AdaptedContent renvoie la charge utile spécifique à l’intégration (par ex. { text } pour LinkedIn), des statistiques d’utilisation de jetons, et l’ID du modèle utilisé.

PublishableIntegration

Publie du contenu vers une API tierce. Utilisé par LinkedIn (et plus tard Mailchimp, X).

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

PublishContext inclut les jetons déchiffrés, le contenu adapté (sortie de adapt()), l’enregistrement de connexion et l’instantané de l’article.

PublishResult rapporte le statut ("ok", "transient_error", "auth_expired", "permanent_error"), un externalRef optionnel (ID de l’article du fournisseur) et un externalUrl optionnel (lien vers l’artefact publié).

WebhookIntegration

Configuré par une URL de webhook collée par l’utilisateur. Utilisé par Slack et Discord.

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

Valide la forme de l’URL et la pingue optionnellement avant de sauvegarder. L’endpoint channelsSaveWebhookConnection appelle ceci avant de chiffrer l’URL.

Type Guards

Le dispatcher utilise des type guards (et non instanceof) pour vérifier les capacités :

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

Matrice actuelle des intégrations